API REST v1 · SDK TypeScript

Cómo integra un desarrollador la API en treinta minutos

Autenticación, primer expediente y el webhook. El camino más corto a algo que funcione.

7 pasos· 30 minutos· Todos los sectores

Interfaz de Code Contract para coordinar documentos y datos
Vista de la plataforma: el proceso coordina documentos y datos hasta el expediente correcto.

Antes de empezar necesitas

  • Una API key del entorno de pruebas
  • El SDK instalado o un cliente HTTP
  • Un endpoint tuyo donde recibir el webhook
  1. Empieza en el entorno de pruebas

    Hay sandbox por organización. Integrar contra producción desde el primer intento es cómo se ensucian los datos reales.

  2. Autentica y lee algo antes de escribir nada

    Un listado de expedientes confirma que la key funciona y qué permisos tiene, sin efectos secundarios.

  3. Crea un expediente de prueba con el SDK

    El SDK de TypeScript evita escribir el cliente HTTP y los reintentos a mano.

  4. Monta el webhook antes de necesitarlo

    Recibir «documento validado» es lo que evita tener que preguntar cada cinco minutos si llegó.

  5. Verifica la firma del webhook

    Un endpoint que acepta cualquier POST es un endpoint que acepta el POST de cualquiera.

  6. Implementa el reintento desde el principio

    Si tu servicio está caído cuando llega el evento, tiene que poder recuperarlo. Un evento perdido en silencio se descubre tarde.

  7. Pasa a producción con una key nueva

    No reutilices la de pruebas. Y con los permisos mínimos que necesite la integración.

Las pantallas cambian, el trámite no Los sistemas oficiales cambian de interfaz sin avisar, así que un botón puede estar en otro sitio del que aquí se dice. Lo que no cambia es el fondo: qué datos hacen falta, qué tiene que cuadrar con qué y qué se comprueba al otro lado.

Los errores que más lo devuelven

Integrar directamente contra producción

Datos reales ensuciados y difíciles de limpiar.

Webhook sin verificar firma

Cualquiera puede llamarlo.

Sin reintento

Los eventos perdidos se descubren cuando ya importan.

Preguntas frecuentes

¿Dónde está la documentación?
En /api/docs de la aplicación, navegable, y el SDK de TypeScript publicado con ejemplos.
¿Hay límites de uso?
Hay rate limiting por API key, generoso para uso normal. Si tu integración hace polling agresivo, conviene pasarse a webhooks.

Procedimiento revisado el . Las normas cambian: si el sistema oficial no se parece a lo que lees aquí, manda la pantalla del sistema.

Esto no es asesoramiento jurídico ni aduanero Es un procedimiento operativo. Para tu caso concreto, y sobre todo si hay una partida en juego, consúltalo con tu transitario o tu asesor.

Cuando cambie algo de este trámite, te avisamos

Una vez al mes: qué obligación entra en vigor, a quién afecta y qué hay que empezar a pedir. Nada más.

Y si lo que quieres es que esto ocurra solo

Pedir el documento, insistir por el canal que el otro sí contesta, leerlo, comprobar que cuadra y dejarlo demostrable: es exactamente lo que hace Code Contract. Sin que la otra parte se registre en nada.

Programar una demo de 30 minutos