Primeros pasos
Cómo funciona
La API permite crear documentos tributarios electrónicos (facturas, boletas, notas de crédito y otros), registrar clientes, contactos, sucursales y productos, y consultar lo que ya está en Matika. Todas las llamadas usan JSON sobre HTTPS y se autentican con un token OAuth 2.0.
Las rutas de esta página son relativas a . El campo de arriba cambia la URL base y actualiza todos los ejemplos.
CompanyId debe ser el identificador de esa misma empresa, escrito exactamente como se lo entregó Matika (no se agregan ni quitan puntos o guion): si no coincide, la operación se rechaza.Seguridad
Autenticación
Con el client_id, el client_secret y el usuario que Matika le entregó se pide un token:
La respuesta trae access_token y su vigencia en expires_in (segundos). Se envía en cada llamada con el encabezado Authorization:
Si el token falta o venció, el servidor responde 401. Pida uno nuevo y repita la llamada.
Formato
Convenciones
- Cuerpos envueltos. Los POST reciben un objeto con una sola propiedad que lleva el nombre del parámetro (por ejemplo
{"DteSiiSDT": [ … ]}). Las respuestas también vienen envueltas ({"DtePostResult": [ … ]}). - El resultado va en el cuerpo, no en el código HTTP. Una operación procesada responde
200aunque haya fallado. ReviseErrorCode: "99" significa que se grabó; cualquier otro valor es un error yErrorMessagedice por qué. - Paginación. Los listados reciben
Pagenumber(desde 1) yPagesize. Una página vacía responde200con la lista vacía y un mensaje "No se encontraron registros" enMessages. - Fechas en formato
AAAA-MM-DD. Montos como número, con punto decimal. - Altas que también actualizan. Clientes, contactos, sucursales y productos se crean si el identificador no existe y se actualizan si ya existe.
Referencia
Códigos de error al emitir documentos
Valores de ErrorCode que devuelve POST /Insert. Orden indica a qué documento corresponde cada resultado. Un documento con varios problemas (por ejemplo, dos productos que no existen) devuelve un resultado por problema, todos con el mismo Orden. Para saber si se grabó, use solo ErrorCode, no el texto de ErrorMessage.
| Código | Qué pasó |
|---|---|
| 99 | Documento grabado. Folio trae el folio asignado. |
| 0 | Dato básico inválido: el CompanyId no es el de su usuario, el tipo de documento o el servicio no existen, o el arreglo venía vacío. |
| 1 | El vendedor (SellerId) no existe. |
| 2 | El cliente (LegEntId) no existe. Créelo antes con /LegalEntity. |
| 3 | La sucursal (SubId o LegEntSubId) no existe. |
| 5 | Un producto del detalle (ProdId) no existe. |
| 6 | El documento no pasó las validaciones de Matika. El detalle viene en ErrorMessage. |
| 7 | Una línea de detalle no pasó las validaciones. |
| 8 · 9 · 10 | Error al grabar el documento, sus pagos o sus imágenes, respectivamente. |
| 12 | El folio informado ya fue enviado al SII y no se puede modificar. |
| 13 | El folio informado no existe. |
Los códigos de POST /DteSiiPay están en su ficha.
En las altas de clientes, contactos, sucursales y productos, "99" también significa éxito; ante cualquier otro código, lea ErrorMessage.
Buenas prácticas
Recomendaciones
- Envíe un documento por llamada.
/Insertacepta un arreglo, pero si un documento del arreglo falla, los que vienen después no se procesan y no aparecen en la respuesta. Con un documento por llamada cada resultado corresponde sin ambigüedad a lo que se envió. - No reintente a ciegas. Si una llamada a
/Insertse corta sin respuesta, el documento puede haberse creado igual. Antes de repetirla, búsquelo con/ListDteSii: un reintento conDteSiiFolio = 0crea un documento nuevo y usa otro folio autorizado por el SII. - Revise el estado en el SII. "99" confirma que el documento se grabó. Si la firma o el envío al SII fallan, el documento queda grabado igual; consulte su estado en
/ListDteSii. - Cree primero los maestros. El cliente, su sucursal y los productos deben existir antes de emitir el documento.
- Mensajes largos.
ErrorMessagellega truncado a 255 caracteres. Si no alcanza para entender el problema, escriba a soporte con elOrdeny la hora de la llamada.
