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.
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
-
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.
-
Autentica y lee algo antes de escribir nada
Un listado de expedientes confirma que la key funciona y qué permisos tiene, sin efectos secundarios.
-
Crea un expediente de prueba con el SDK
El SDK de TypeScript evita escribir el cliente HTTP y los reintentos a mano.
-
Monta el webhook antes de necesitarlo
Recibir «documento validado» es lo que evita tener que preguntar cada cinco minutos si llegó.
-
Verifica la firma del webhook
Un endpoint que acepta cualquier POST es un endpoint que acepta el POST de cualquiera.
-
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.
-
Pasa a producción con una key nueva
No reutilices la de pruebas. Y con los permisos mínimos que necesite la integración.
Matriz de control para cómo integra un desarrollador la API en treinta minutos
No basta con completar los pasos: cada uno debe dejar una entrada identificada, una comprobación explícita y una evidencia que otra persona pueda revisar sin reconstruir el trámite.
| Paso | Entrada necesaria | Control de excepción | Evidencia de cierre |
|---|---|---|---|
| 1. Empieza en el entorno de pruebas | Para cómo integra un desarrollador la API en treinta minutos: Una API key del entorno de pruebas | En cómo integra un desarrollador la API en treinta minutos, integrar directamente contra producción: Datos reales ensuciados y difíciles de limpiar. | El cierre de cómo integra un desarrollador la API en treinta minutos responde a «¿Dónde está la documentación?»: En /API/docs de la aplicación, navegable, y el SDK de TypeScript publicado con ejemplos. |
| 2. Autentica y lee algo antes de escribir nada | Para cómo integra un desarrollador la API en treinta minutos: El SDK instalado o un cliente HTTP | En cómo integra un desarrollador la API en treinta minutos, webhook sin verificar firma: Cualquiera puede llamarlo. | El cierre de cómo integra un desarrollador la API en treinta minutos responde a «¿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. |
| 3. Crea un expediente de prueba con el SDK | Para cómo integra un desarrollador la API en treinta minutos: Un endpoint tuyo donde recibir el webhook | En cómo integra un desarrollador la API en treinta minutos, sin reintento: Los eventos perdidos se descubren cuando ya importan. | El cierre de cómo integra un desarrollador la API en treinta minutos responde a «¿Dónde está la documentación?»: En /API/docs de la aplicación, navegable, y el SDK de TypeScript publicado con ejemplos. |
| 4. Monta el webhook antes de necesitarlo | Para cómo integra un desarrollador la API en treinta minutos: Una API key del entorno de pruebas | En cómo integra un desarrollador la API en treinta minutos, integrar directamente contra producción: Datos reales ensuciados y difíciles de limpiar. | El cierre de cómo integra un desarrollador la API en treinta minutos responde a «¿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. |
| 5. Verifica la firma del webhook | Para cómo integra un desarrollador la API en treinta minutos: El SDK instalado o un cliente HTTP | En cómo integra un desarrollador la API en treinta minutos, webhook sin verificar firma: Cualquiera puede llamarlo. | El cierre de cómo integra un desarrollador la API en treinta minutos responde a «¿Dónde está la documentación?»: En /API/docs de la aplicación, navegable, y el SDK de TypeScript publicado con ejemplos. |
| 6. Implementa el reintento desde el principio | Para cómo integra un desarrollador la API en treinta minutos: Un endpoint tuyo donde recibir el webhook | En cómo integra un desarrollador la API en treinta minutos, sin reintento: Los eventos perdidos se descubren cuando ya importan. | El cierre de cómo integra un desarrollador la API en treinta minutos responde a «¿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. |
| 7. Pasa a producción con una key nueva | Para cómo integra un desarrollador la API en treinta minutos: Una API key del entorno de pruebas | En cómo integra un desarrollador la API en treinta minutos, integrar directamente contra producción: Datos reales ensuciados y difíciles de limpiar. | El cierre de cómo integra un desarrollador la API en treinta minutos responde a «¿Dónde está la documentación?»: En /API/docs de la aplicación, navegable, y el SDK de TypeScript publicado con ejemplos. |
Los errores que más lo devuelven
Datos reales ensuciados y difíciles de limpiar.
Cualquiera puede llamarlo.
Los eventos perdidos se descubren cuando ya importan.
Preguntas frecuentes
¿Dónde está la documentación?
¿Hay límites de uso?
Texto listo para copiar y pegar en tu usuario
Completa los campos entre corchetes y pégalo para empezar a configurar el proceso con tu contexto.
Quiero poner en marcha este proceso: Cómo integra un desarrollador la API en treinta minutos.
Mi contexto:
- Empresa o equipo: [indicar]
- Personas o sistemas que aportan información: [indicar]
- Destino final de los datos o documentos: [indicar]
- Frecuencia y fecha límite: [indicar]
Configura conmigo estos pasos:
1. Empieza en el entorno de pruebas
2. Autentica y lee algo antes de escribir nada
3. Crea un expediente de prueba con el SDK
4. Monta el webhook antes de necesitarlo
5. Verifica la firma del webhook
6. Implementa el reintento desde el principio
7. Pasa a producción con una key nueva
Para cada paso, pregúntame qué entra, quién responde, cómo se valida, qué ocurre si falla y qué evidencia queda. No inventes datos que no te haya facilitado.Procedimiento revisado el . Las normas cambian: si el sistema oficial no se parece a lo que lees aquí, manda la pantalla del sistema.
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