Saltar al contenido principal

Primeros pasos

Antes de tu primera llamada necesitas tres cosas. Dos las hace el equipo de Contadito y una la haces tú.

1. Que tu empresa tenga la integración habilitada​

Facturar por API requiere que tu empresa tenga configurados —una sola vez— el punto de emisión, el usuario emisor, la lista de precios y la configuración de cobro. Nada de eso viaja en tus solicitudes: se lee de la configuración de tu empresa.

Mientras eso no exista, toda llamada autenticada responde:

{
  "code": "INTEGRATION_NOT_ENABLED",
  "message": "..."
}

Y si está habilitada pero incompleta, verás un 409 con un código INTEGRATION_MISSING_*. En ambos casos la solución no está de tu lado: escríbele a tu contacto en Contadito.

2. Que tus productos estén mapeados​

En cada línea de factura mandas tu propio identificador de producto en externalProductId (tu SKU, tu id interno, lo que uses). Contadito lo traduce a un producto suyo, con su precio y su tasa de ISV.

Ese mapeo lo carga el personal de Contadito. En v1 no hay endpoint para consultar ni crear el catálogo. Un id sin mapear se rechaza con:

{
  "code": "PRODUCT_NOT_FOUND",
  "message": "..."
}

Este es, de lejos, el primer error que golpea a casi toda integración nueva. Manda la lista completa de tus SKUs antes de empezar a programar.

consejo

El externalProductId es una cadena y es tuya. Elige algo estable: si mañana renumeras tus SKUs, hay que rehacer el mapeo.

3. Tu API key​

Un administrador de tu empresa la emite desde la app de Contadito, en la pantalla de API keys.

Acceso a la configuración​

Para llegar a la sección de API keys, sigue estos pasos:

  1. Desde la pantalla principal de Contadito, localiza el menú lateral izquierdo
  2. Navega a Configuración → Integración de facturación externa Configuración01
  3. En la página que se abre, selecciona la pestaña "API keys" Configuración02
  • La key se ve así: ctd_sk_a1b2c3d4…
  • Se muestra una sola vez. Cuando cierras ese diálogo ya no se puede recuperar; solo queda el prefijo para identificarla en la lista.
  • Cada empresa puede tener hasta 2 keys activas a la vez. Eso es a propósito: es justo lo necesario para rotar sin cortar el servicio (emites la segunda, la despliegas, revocas la primera).
  • Puedes revocarla en cualquier momento, y el corte es inmediato.

Guárdala como guardas una contraseña de base de datos: en el gestor de secretos de tu infraestructura, nunca en el repositorio ni en el frontend.

Comprueba que todo respira​

curl https://integration.contadito.com/v1/health
{ "status": "ok" }

Ese endpoint no pide autenticación, justamente para que puedas distinguir "la API está caída" de "mi credencial está mal" antes de escalar el problema.

Ahora sí, y en este orden: primero prueba tu integración sin emitir nada, y después emite tu primera factura.

Última actualización en