{"info":{"_postman_id":"da9a5a94-8e8f-4863-a18e-1a71e9caa420","name":"EMITE - Referencia de la API","description":"

¡BIENVENIDO!

Bienvenido a la documentación de nuestros servicios de certificación. En esta página encontrarás los recursos disponibles en nuestro servicio así como actualizaciones y ejemplos de uso en distintos lenguajes. Si deseas probar nuestros servicios en un ambiente de integración (staging), ponte en contacto con nosotros.

¡Nos encanta tenerte aqui!

Nosotros

EMITE es una organización visionaria y emprendedora, que busca apoyar a todas las personas, empresas y corporaciones que requieren de servicios de tecnología en materia de comprobación fiscal digital. EMITE cuenta con la certificación por parte del SAT, para poder timbrar Comprobantes Fiscales Digitales a través de Internet (CFDI), con el número de autorización 56080.

Conoce un poco más de nosotros en: https://www.emite.mx/conocenos

Arquitectura

Nuestra misión es diseñar soluciones sencillas, rápidas y seguras que ayuden a nuestros clientes a crear aplicaciones sofisticadas, con mayor flexibilidad, escalabilidad y fiabilidad que cumplan con los requisitos más exigentes.

Hemos puesto nuestro mayor esfuerzo en I+D para adoptar las tecnologías más innovadoras. Con una arquitectura totalmente cloud y serverless, de la mano de Amazon Web Services, buscamos redefinir el concepto de servicios de certificación CFDI en México.

EMITE es Partner Nivel Select de la red de socios de Amazon Web Services.

Referencia de la API

La API está basada en el protocolo REST. Nuestra API tiene direcciones URL predecibles orientadas a los recursos. Acepta y devuelve cuerpos de solicitud codificados en JSON y utiliza códigos de respuesta HTTP estándar, autenticación y verbos.

Puedes usar la API en modo de integración apuntando al ambiente staging, esto no afecta tus datos en vivo ni interactua con el SAT en producción. La URL base y la autenticación determina si la solicitud está en modo producción o staging.

Autenticación

El proceso de autenticación está basado en el estandar JSON Web Token que permiten la propagación de identidad y privilegios. El JWT te servirá para identificar cada llamada al servicio de EMITE y garantizarás que nadie pueda obtener acceso a tu información. Cada JWT es configurado para ser utilizado ya sea en modo staging o producción y para cada uno de estos modos obtendrás un JWT diferente para llamadas entre servidores.

Asegúrate de nunca compartir tu JWT ya que este tiene acceso a todos los privilegios de tu cuenta.

Para autenticarte es necesario configurar la cabecera \"Authorization\" y anteponer la palabra Bearer.

-H \"Authorization: Bearer eyJhbGc...\"

\n\n

Versiones

Todos los cambios que hacemos al API y que son incompatibles con versiones anteriores son liberados en una versión nueva. La versión actual es la v1. En caso de hacer un cambio entre versiones, recomendamos probar la aplicación con la nueva versión antes de hacer el cambio completo en tu aplicación.

Cuando se soluciona algún error en el sistema, la versión sigue siendo la misma, así que no tendrás qué hacer un cambio de versión salvo sean agregadas funcionalidades nuevas.

¿request_id?

Te darás cuenta que en todas las peticiones se regresa el valor \"request_id\". Este dato es muy importante para poder levantar incidencias o poder trazabilizar las operaciones que realices y será de mucha utilidad para las operaciones de debuggeo en conjunto. Te recomendamos tenerlo siempre a la mano.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"887256","collectionId":"da9a5a94-8e8f-4863-a18e-1a71e9caa420","publishedId":"S17m1ri8","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2019-03-14T23:57:20.000Z"},"item":[{"name":"Timbrar documento","id":"0255cc95-b39b-4fd6-bbcf-bf9b21c14b1b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"description":"

JWT de autenticación.

\n","key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"},{"description":"

Opcional Identificador interno del cliente.

\n","key":"X-ref-id","type":"text","value":"GUIDCliente"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"xml","value":"base64","description":"

XML cifrado en base64.

\n","type":"text"},{"key":"return_method","value":"string (Catálogo: url|base64)","description":"

Opcional Método de retorno del XML certificado. Opciones: base64 (Default, Devuelve el XML cifrado en base64). url (Devuelve una URL firmada con vigencia de 5 minutos para descargarlo vía GET).

\n","type":"text"}]},"url":"https://api-stage.emite.dev/v1/documents","description":"

Este método provee un único punto de certificación entre EMITE y sus clientes. Este método analiza el tipo de documento y ejecuta el proceso de validación dependiendo de su conformación.

Este método permite enviar:

CFDI versión 4.0 y todos sus complementos (Carta Porte 2.0, Pagos 2.0, Comercio Exterior 2.0, etc.)
\n
CFDI de retenciones e información de pagos versión 2.0
\n

Flujo

El documento deberá ser enviado vía HTTPS POST en el atributo \"xml\" cifrado en base64.

Cuando se determina el tipo de documento, se valida su estructura (XSD), la información contenida contra la matriz de validaciones adicionales correspondientes y criptografía. Si el documento es válido, se asignará un TFD 1.0, TFD 1.1 o SD 1.0 dependiendo de la regulación vigente y el tipo de documento.

Autenticación

La autenticación se configura en la cabezera \"Authorization\" con un JSON Web Token firmado por EMITE.

Idempotencia

En matemática y lógica, la idempotencia es la propiedad para realizar una acción determinada varias veces y aun así conseguir el mismo resultado que se obtendría si se realizase una sola vez. Un elemento que cumple esta propiedad es un elemento idempotente, o un idempotente.

A cada documento digital que se timbra, EMITE le asigna un identificador único (UUID), pero ¿qué ocurre si por equivocación envío nuevamente el documento? o peor aún, mi sistema se cicla y envía el documento N veces. Si el documento se timbra en más de una ocasión, se asignará un nuevo UUID y será entregado al SAT como un documento diferente, por lo tanto, la autoridad reconocerá que tienes 2 CFDI (o más) y no diferenciará si fue error humano o fueron emitidas realmente.

Con el fin de evitar la duplicidad de documentos, nuestro servicio tiene 2 flujos de validación.

Validación integral de información (método hash)
Validación por ref-id

Validación integral de información

La validación integral toma ciertos atributos que en la operación diaria son \"irrepetibles\" en un documento y los concatena para obtener un identificador. Los datos que se toman son:

RFC Emisor
RFC Receptor
Año-Mes
Tipo de comprobante
Serie
Folio
Total
TipoRelacion (en caso de existir)
UUIDRelacionado (en caso de existir)

En caso de ser un complemento de recepción de pagos se incluirán los siguientes atributos:

Fecha del pago
Forma del pago
Monto
ID del documento relacionado
Número de parcialidad
Importe del saldo anterior
Importe del saldo insoluto

En caso de ser un complemento de nómina se incluirán los siguientes atributos:

Tipo de nómina
Fecha del pago
Fecha inicial de pago
Fecha final de pago

Esta cadena se hashea en SHA256 y se utiliza como llave para identificar documentos timbrados previamente.

Validación por ref-id

Es común que los sistemas le asignen un identificador a cada documento aún antes de enviarlo a timbrar. Este identificador será irrepetible y podremos identificar cuando por algún motivo vuelvas a mandar el mismo comprobante, y de esta forma, no duplicar el CFDI. Es importante mencionar que si mandas de nuevo el \"ref-id\", aún y cuando el documento enviado sea totalmente diferente al timbrado, se regresará el documento previo.

Para utilizar el ref-id, es necesario enviar en la cabecera de la petición el atributo \"X-ref-id\" con el valor interno.

-H \"X-ref-id:ID021342\"

\n\n

En ambos casos, encontrarás el resultado del hash en el atributo *\"data:document_info:fingerprint\"*.

Retorno

En caso de que el documento sea correcto y pase todas las validaciones se firmará y el objeto de retorno será cfdi40 o ret20. El documento regresará en el atributo \"data:xml_info:xml\" (base64) o \"data:xml_info:url\" (URL firmada con vigencia de 5 minutos) dependiendo de la solicitud.

En caso contrario, se regresará un objeto error con el detalle de los errores en el atributo \"data:details\".

\n","urlObject":{"protocol":"https","path":["v1","documents"],"host":["api-stage","emite","dev"],"query":[],"variable":[]}},"response":[{"id":"6450a420-d7e8-4228-b1eb-acae86d3fabc","name":"Timbrado exitoso","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"}],"body":{"mode":"raw","raw":"{\n\t\"xml\":\"PD94...\",\n\t\"return_method\": \"base64\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api-stage.emite.dev/v1/documents"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Region","value":"us-east-1 (N. Virginia)"}],"cookie":[],"responseTime":null,"body":"{\r\n \"object\": \"cfdi40\",\r\n \"livemode\": false,\r\n \"data\": {\r\n \"status\": \"stamped\",\r\n \"document_info\": {\r\n \"xml\": \"PD94...\",\r\n \"certificate\": \"20001000000300022699\",\r\n \"signature\": \"l5P1+FNUxnO8G55su35mrwVyKsFqltyHU8kMm5Cmbco2q2hxoYDUnm8ZD6cvvdHRnVX0G67R2XefssRy11iZ/M6dtR9nRFc3VtXyt8w8MMDCHyV10cynmUynKI7z+kNQF0U05A2P17o8ADlnLbZOC0kOjrjQ1FveOO7OOTth//GY6wwIevRAOH/7hKckAYNeIzDlc32usY1o1RZ0ltexVL9ZMWxB7I8bVGpwHXwK+jvn5O0pd0zsFohdsQTYHqSSYcecb/UT4euQwAQDL4eJ+KkYmZtFNZkCT3J+QKIdA9W4SxCE3RsHLAnA1swYZhEZcncisr9GMeyDD5H/1O8cBA==\",\r\n \"issuer\": \"AAQM610917QJA\",\r\n \"recipient\": \"XAXX010101000\",\r\n \"serie\": \"BENGALA\",\r\n \"folio\": \"1\",\r\n \"total\": \"1.16\",\r\n \"created_at\": \"2019-06-25T00:00:00\",\r\n \"fingerprint\": \"31a64e3b744a66019d267503a2b48eaa14e2dee4\"\r\n },\r\n \"stamp_info\": {\r\n \"type\": \"tfd11\",\r\n \"xml\": \"PHRmZDpUaW1icmVGaXNjYWxEaWd.....\",\r\n \"uuid\": \"EEEEEEEE-BB2C-4926-A19C-E1C26BA68D92\",\r\n \"signature\": \"mW/NP1rYBa5bzX50XRoCNV05xVJ4CM2BDSLJZBSsTOT6HMBkecvHZEpr8qYLnmv2TkeUuO2TU+RCsCZy/3PdaFrXW9ur4xbOrQcAW+AzUNNfdaWILOfwXcUWYOr03uIl0XOOEwmm3AeTczb+VJ7edn4lD5wM0TQHaWMDmgO+bWsUIXKlfvmyjSenNNeK9/Cii0D/mmppbJ9/e5sRuSux1Gf06MyEIS1K+U6XqW2BL4puj+BpeVXoJz/GGRMAgnZs5eSiG+mzZwRJf+coyRxkG1ERF1r6t3hwYkIZVwRnR2sedZmHyg2XSpZw2KZA+94CuIJnhmThBuNQr3MIrIZJLQ==\",\r\n \"created_at\": \"2019-06-25T13:57:14\",\r\n \"certificate\": \"20001000000300022323\",\r\n \"provider\": \"EFA100217SU5\",\r\n \"legend\": \"Este documento fue timbrado en el ambiente de pruebas de EMITE - Soluciones Fiscales Digitales, Proveedor Autorizado de Certificación: 56080\",\r\n \"original_chain\": \"||1.1|EEEEEEEE-BB2C-4926-A19C-E1C26BA68D92|2019-06-25T13:57:14|EFA100217SU5|Este documento fue timbrado en el ambiente de pruebas de EMITE - Soluciones Fiscales Digitales, Proveedor Autorizado de Certificación: 56080|l5P1+FNUxnO8G55su35mrwVyKsFqltyHU8kMm5Cmbco2q2hxoYDUnm8ZD6cvvdHRnVX0G67R2XefssRy11iZ/M6dtR9nRFc3VtXyt8w8MMDCHyV10cynmUynKI7z+kNQF0U05A2P17o8ADlnLbZOC0kOjrjQ1FveOO7OOTth//GY6wwIevRAOH/7hKckAYNeIzDlc32usY1o1RZ0ltexVL9ZMWxB7I8bVGpwHXwK+jvn5O0pd0zsFohdsQTYHqSSYcecb/UT4euQwAQDL4eJ+KkYmZtFNZkCT3J+QKIdA9W4SxCE3RsHLAnA1swYZhEZcncisr9GMeyDD5H/1O8cBA==|20001000000300022323||\",\r\n \"validation_url\": \"https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=EEEEEEEE-BB2C-4926-A19C-E1C26BA68D92&re=AAQM610917QJA&rr=XAXX010101000&tt=1.16&fe=1O8cBA==\"\r\n }\r\n },\r\n \"request_id\": \"39601972-b88c-45d4-a2b6-1f9b7292496b\"\r\n}"},{"id":"32b5c8fe-b54d-4682-abe9-bd37d363a429","name":"Intento de timbrado con error","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"}],"body":{"mode":"raw","raw":"{\n\t\"xml\":\"PD94...\",\n\t\"return_method\": \"base64\"\n}"},"url":"https://api-stage.emite.dev/v1/documents"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"X-Region","value":"us-east-1 (N. Virginia)","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\r\n \"object\": \"error\",\r\n \"livemode\": false,\r\n \"data\": {\r\n \"status\": \"parameter_validation_error\",\r\n \"count\": 1,\r\n \"details\": [\r\n {\r\n \"code\": \"CFDI33196\",\r\n \"description\": \"El valor de los campos MetodoPago y FormaPago son incompatibles.\",\r\n \"validation\": \"Si se declara el atributo MetodoPago con el valor \\\"PUE\\\" el atributo FormaPago debe declarar valor un valor diferente a \\\"99\\\".\",\r\n \"clue\": null\r\n }\r\n ]\r\n },\r\n \"request_id\": \"e103772a-4182-4d98-82f6-22a592ec6a7f\"\r\n}"}],"_postman_id":"0255cc95-b39b-4fd6-bbcf-bf9b21c14b1b"},{"name":"Recuperar XML timbrado","id":"d1ea7508-4e97-42c3-92f4-91f5afc78763","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"description":"

JWT de autenticación.

\n","key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"}],"url":"https://api-stage.emite.dev/v1/documents/:uuid/xml","description":"

El objetivo de este método es recuperar el documento XML timbrado.

Solo podrás recuperar los documentos que hayas procesado con el JWT que envíes.

Flujo

Deberás enviar el UUID del documento que deseas recuperar como penúltimo parámetro de la URL.

Autenticación

La autenticación se configura en la cabezera \"Authorization\" con un JSON Web Token firmado por EMITE.

Retorno

El documento XML regresará cifrado en base64 dentro del atributo \"data:xml\".

\n","urlObject":{"protocol":"https","path":["v1","documents",":uuid","xml"],"host":["api-stage","emite","dev"],"query":[],"variable":[{"description":{"content":"

UUID del documento timbrado

\n","type":"text/plain"},"type":"string","value":"","key":"uuid"}]}},"response":[{"id":"63fb84cf-c504-47e5-9490-bb5a29cc370b","name":"Recuperación exitosa","originalRequest":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"}],"url":"https://api-stage.emite.dev/v1/documents/EEEEEEEE-BB2C-4926-A19C-E1C26BA68D92/xml"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"X-Region","value":"us-east-1 (N. Virginia)","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"object\": \"document_xml\",\n \"livemode\": false,\n \"data\": {\n \t\"type\": \"cfdi40\",\n \"document\": \"PD94...\"\n },\n \"request_id\": \"2515a3bc-3b04-4cef-84f6-cee2658af262\"\n}"}],"_postman_id":"d1ea7508-4e97-42c3-92f4-91f5afc78763"},{"name":"Recuperar acuse de recepción SAT","id":"b5790ccc-8f51-49be-aa24-43e566d1e5f6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"description":"

JWT de autenticación.

\n","key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"}],"url":"https://api-stage.emite.dev/v1/documents/:uuid/sat","description":"

El objetivo de este método es recuperar el acuse de recepción firmado por el SAT.

Solo podrás recuperar los documentos que hayas procesado con el JWT que envíes.

Flujo

Deberás enviar el UUID del documento que deseas recuperar como penúltimo parámetro de la URL.

Autenticación

La autenticación se configura en la cabezera \"Authorization\" con un JSON Web Token firmado por EMITE.

Retorno

El documento XML regresará cifrado en base64 dentro del atributo \"data:xml\".

\n","urlObject":{"protocol":"https","path":["v1","documents",":uuid","sat"],"host":["api-stage","emite","dev"],"query":[],"variable":[{"description":{"content":"

UUID del documento timbrado

\n","type":"text/plain"},"type":"string","value":"","key":"uuid"}]}},"response":[{"id":"90599eda-daa6-4a3a-86d2-9a8033ae240f","name":"Recuperación exitosa","originalRequest":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"}],"url":"https://api-stage.emite.dev/v1/documents/EEEEEEEE-BB2C-4926-A19C-E1C26BA68D92/sat"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"X-Region","value":"us-east-1 (N. Virginia)","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"object\": \"document_sat\",\n \"livemode\": false,\n \"data\": {\n \t\"type\": \"sat_aknowlement\",\n \"document\": \"PD94...\"\n },\n \"request_id\": \"4325fc27-75d4-4eb2-827c-656619aa1d5f\"\n}"}],"_postman_id":"b5790ccc-8f51-49be-aa24-43e566d1e5f6"},{"name":"Recuperar PDF","id":"9ab71895-f5f4-412b-8563-7295274faf78","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"description":"

JWT de autenticación.

\n","key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"}],"url":"https://api-stage.emite.dev/v1/documents/:uuid/pdf?regenerate=true&template=template_name","description":"

El objetivo de este método es recuperar la representación impresa del documento (PDF).

Solo podrás recuperar los documentos que hayas procesado con el JWT que envíes.

Flujo

Deberás enviar el UUID del documento que deseas recuperar como último parámetro de la URL.

Autenticación

La autenticación se configura en la cabezera \"Authorization\" con un JSON Web Token firmado por EMITE.

Retorno

El documento PDF regresará cifrado en base64 dentro del atributo \"data:pdf\".

\n","urlObject":{"protocol":"https","path":["v1","documents",":uuid","pdf"],"host":["api-stage","emite","dev"],"query":[{"description":{"content":"

Opcional true en caso de que se desee regenerar, false (default) en caso de que se desee obtener el PDF generado anteriormente.

\n","type":"text/plain"},"key":"regenerate","value":"true"},{"description":{"content":"

Opcional Nombre de la plantilla que se utilizará.

\n","type":"text/plain"},"key":"template","value":"template_name"}],"variable":[{"description":{"content":"

UUID del documento timbrado

\n","type":"text/plain"},"type":"string","value":"","key":"uuid"}]}},"response":[{"id":"4ba261b7-bf3c-4e79-bf81-d4b206f8bc68","name":"Recuperación exitosa","originalRequest":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"},{"description":"JWT de autenticación","key":"Authorization","type":"text","value":"Bearer ponte.en.contacto"}],"url":{"raw":"https://api-stage.emite.dev/v1/documents/EEEEEEEE-BB2C-4926-A19C-E1C26BA68D92/pdf?regenerate=true&template=template_name","protocol":"https","host":["api-stage","emite","dev"],"path":["v1","documents","EEEEEEEE-BB2C-4926-A19C-E1C26BA68D92","pdf"],"query":[{"key":"regenerate","value":"true","description":"true en caso de que se desee regenerar, false en caso de que se desee consultar el PDF generado anteriormente"},{"key":"template","value":"template_name","description":"Nombre de la plantilla que se utilizará"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"X-Region","value":"us-east-1 (N. Virginia)","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"object\": \"recover_pdf\",\n \"livemode\": false,\n \"data\": {\n \t\"type\": \"pdf\",\n \"document\": \"UVER...\"\n },\n \"request_id\": \"2515a3bc-3b04-4cef-84f6-cee2658af262\"\n}"}],"_postman_id":"9ab71895-f5f4-412b-8563-7295274faf78"}],"event":[{"listen":"prerequest","script":{"id":"d156bab4-d3ca-45ba-9752-96a3121a674f","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5f95551a-3997-417c-9e18-b71e01e9f6c5","type":"text/javascript","exec":[""]}}]}