Saltar al contenido principal

Empieza probando

Toda integración nueva empieza aquí. Cada POST /v1/invoices emite una factura legal: consume un correlativo del rango CAI de tu empresa, queda registrada y no se puede borrar. Anularla se hace a mano desde la app de Contadito.

Por eso, mientras estás construyendo tu integración, no llames a ese endpoint. Llama a POST /v1/invoices/preview.

Qué es la previsualización​

El mismo body, el mismo motor de cálculo y la misma plantilla de impresión que una factura real, con tu configuración: tus productos mapeados, tu lista de precios, tus tasas de ISV, tu membrete. Al final el documento se descarta.

  • No consume CAI ni avanza el correlativo.
  • No escribe nada: todo lo que hace son lecturas.
  • No lleva Idempotency-Key: no hay nada que reintentar.
  • Devuelve los totales y el PDF en pdfBase64.

Repítela cuantas veces quieras. No hay nada que limpiar después.

curl -s -X POST https://integration.contadito.com/v1/invoices/preview \
  -H "Authorization: Bearer $CONTADITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "externalProductId": "SKU-WEB-HOSTING-01", "quantity": 2 }
    ]
  }'

Qué deberías validar antes de emitir​

  1. Tus SKUs están mapeados. Un externalProductId sin mapeo da PRODUCT_NOT_FOUND. Es el primer error de casi toda integración nueva.
  2. Los precios y el ISV salen como esperas. Compara unitPrice, taxBreakdown y total contra lo que tu sistema cree que debe cobrar. Si vas a mandar precios negociados con items[].price, pruébalos aquí: en productos en dólares o parcialmente gravados el total no sale de una regla de tres.
  3. El PDF se ve bien. Guarda pdfBase64 en un archivo y ábrelo: membrete, datos del cliente, desglose y total en letras.
  4. Los casos raros de tu negocio. Ventas exentas, exoneradas (con clientId y RTN), varias tasas de ISV en la misma factura, productos en dólares.
  5. Tu manejo de errores. Manda un SKU inexistente, un clientId que no es tuyo, un body con un campo de más, y comprueba que programas contra code.
peligro

El PDF de una previsualización no es un comprobante

Sale marcado SIN VALIDEZ FISCAL y con el CAI enmascarado. Sirve para que tú revises el formato, no para entregárselo a un cliente.

Cuando ya necesites emitir de verdad​

La previsualización cubre precios, impuestos y formato, pero hay dos cosas que solo existen en la emisión real: el Idempotency-Key y los ids que tienes que persistir.

Antes de tu primera factura de producción:

  • Ten resuelto Idempotencia y reintentos. La key se persiste antes de la primera llamada.
  • Guarda el id que devuelve la factura: en v1 no hay listado de facturas.
  • Si vas a emitir facturas de prueba de verdad, pídele a tu contacto en Contadito una empresa de prueba con su propia key y su propio rango. No emitas pruebas contra tu empresa de producción.

Y después​

Última actualización en