Integra tu sistema con ODYM API v1

De tu primera clave al comprobante

La integración se ejecuta siempre desde tu backend. ODYM valida, numera y procesa el documento sin exponer credenciales de SUNAT ni del proveedor fiscal.

Autenticación y ambientes

Envía la API key como Bearer token. Cada RUC y cada ambiente debe usar una clave independiente.

Authorization: Bearer odym_test_REEMPLAZAR
Accept: application/json
X-Request-ID: erp-operacion-000001

odym_test_ opera en sandbox. odym_live_ realiza emisiones reales en producción. La clave nunca debe llegar al navegador, una app móvil o un repositorio.

Endpoints principales

Todos los recursos están aislados por cuenta, empresa, API key y ambiente.

Emitir una factura

Usa numbering_mode: "odym" para que ODYM asigne la serie fiscal configurada y reserve el correlativo de forma segura.

{
  "schema_version": "1.0",
  "numbering_mode": "odym",
  "document_type": "invoice",
  "external_id": "ERP-FACTURA-12345",
  "document": {
    "issue_date": "2026-09-10",
    "currency": "PEN",
    "operation_type": "0101",
    "customer": {
      "document_type": "6",
      "document_number": "20100070970",
      "legal_name": "CLIENTE EMPRESA S.A.C."
    },
    "payment": { "type": "cash" },
    "items": [{
      "code": "SERV-001",
      "description": "Servicio de consultoría",
      "unit_code": "ZZ",
      "quantity": "1",
      "unit_value": "100.000000",
      "line_value": "100.00",
      "tax": { "category": "taxable", "rate": "18", "amount": "18.00" },
      "icbper_amount": "0.00",
      "line_total": "118.00"
    }],
    "totals": {
      "taxable": "100.00", "exempt": "0.00", "unaffected": "0.00",
      "export": "0.00", "free": "0.00", "igv": "18.00",
      "icbper": "0.00", "total": "118.00"
    }
  }
}

Respuesta inicial

{
  "data": {
    "submission_id": "01K4EXAMPLE7R4YQ9C2D6J8M",
    "external_id": "ERP-FACTURA-12345",
    "document_type": "invoice",
    "environment": "sandbox",
    "status": "queued",
    "operational_status": "queued",
    "requires_reconciliation": false,
    "document_number": {
      "managed_by": "odym",
      "series": "F001",
      "correlative": "25",
      "formatted": "F001-00000025"
    },
    "artifacts": []
  },
  "meta": {
    "request_id": "erp-operacion-000001",
    "api_version": "v1"
  }
}

Tipos documentales admitidos

Los campos específicos de notas, guías, retenciones, percepciones y lotes están definidos en la especificación OpenAPI oficial.

Idempotencia sin duplicados

Cada POST /submissions requiere un Idempotency-Key de 8 a 128 caracteres. Reutiliza la misma clave y el mismo cuerpo cuando no sepas si recibiste la respuesta.

Estados, polling y artefactos

Consulta el mismo submission_id. Un intervalo sugerido es 2 s, 3 s, 5 s, 8 s, 13 s y luego cada 30 s, respetando siempre Retry-After y next_check_at.

Si hay un fallo, failure_diagnosis informa el código, el motivo original y la siguiente acción. automatic y next_attempt_at indican la recuperación programada; requires_action señala cuándo debes revisar datos o configuración. ODYM puede sincronizar el token automáticamente, pero conserva los datos fiscales y el motivo de un CDR rechazado.

curl "https://odymfactura.com/api/v1/submissions/{submission_id}/artifacts/pdf" \
  --header "Authorization: Bearer $ODYM_API_KEY" \
  --output comprobante.pdf

Conexión automática

Un sistema externo puede autenticar al usuario de ODYM, listar sus empresas y generar una API key sin pedirle que copie el secreto manualmente.

Manejo de errores

Todas las respuestas de error incluyen un código estable, un mensaje y el request_id para trazabilidad.

{
  "error": {
    "code": "validation_failed",
    "message": "La solicitud no cumple el contrato de ODYM API v1.",
    "details": { "fields": {} }
  },
  "meta": { "request_id": "erp-operacion-000001" }
}

Antes de pasar a producción

Completa el piloto en sandbox y conserva evidencia técnica sin guardar API keys ni documentos completos en logs.

1. GET /company confirma el RUC esperado y el ambiente sandbox.
2. Una boleta y una factura válidas terminan en accepted u observed.
3. PDF y XML se descargan desde el backend y coinciden con sus hashes.
4. Repetir un POST con la misma idempotencia no crea otro documento.
5. Un total incorrecto responde 422 y no genera una emisión.
6. Una falla de descarga o correo reintenta solo esa entrega.
7. La clave odym_live_ tiene permisos mínimos y está guardada como secreto.
8. La empresa está habilitada, su numeración está lista y las series productivas son correctas.