Servicios Web de SUNAT

Para informar nuestros comprobantes electr贸nicos (XML) emitidos a SUNAT, disponemos de algunos servicios SOAP a los que necesitamos conectarnos para enviar estos archivos.

Credenciales#

Para conectarnos a estos servicios, necesitaremos unas credenciales, estas son la misma que la clave SOL.

DatoRelaci贸n con clave SOL
Usuario SOAPRUC + Usuario SOL
Clave SOAPclave SOL

Ejemplo:

  • Usuario: 20123456789MODDATOS
  • Clave: moddatos
Usuario Secundario

Es recomendable crear un usuario secundario con solo permisos para procesos de facturaci贸n electr贸nica, y evitar utilizar la clave SOL principal. Puedes encontrar muchos tutoriales en internet, pero recuerda que para que el usuario este operativo puede tomar hasta 24 horas despues de su creaci贸n.

BillService#

Este es el principal servicio SOAP, el cual define 3 metodos:

  • sendBill: Para enviar comprobantes (FAC, BOL, NCR, NDB, RET, PERC, GRM).
  • sendSummary: Para enviar resumen diario, comuncaiones de baja, reversiones.
  • getStatus: Consultar el estado del env铆o de un resumen diario, c. de baja, reversiones.

Para ver el detalle de los m茅todos, puedes revisar el Manual del Programador - SUNAT

Existen 3 endpoints del mismo servicio para diferentes comprobantes.

  1. Facturas, Boletas, notas de cr茅dito, d茅bito, Resumen diario de boletas, Comunicacion de bajas
  2. Retenci贸n, Percepci贸n, Resumen de Reversiones
  3. Guia de Remisi贸n

Endpoints#

SUNAT dispone de servicios para prueba (BETA) y producci贸n:

BillConsultService#

Este servicio se utiliza para consultar el estado de comprobantes previamente enviados y obtener el CDR, tener en cuenta que solo esta habilitado para facturas y notas de cr茅dito, d茅bito releacionadas.

M茅todos SOAP:

  • getStatus: Consultar el estado de un comprobante previamente enviado.
  • getStatusCdr: Para obtener el CDR, si el comprobante fue previamente procesado.

Endpoints#

El servicio solo esta disponible en produci贸n.

ServicioRuta
Consulta CDRhttps://e-factura.sunat.gob.pe/ol-it-wsconscpegem/billConsultService?wsdl

Nomenclatura#

SUNAT exige que el nombre del archivo XML siga un formato espec铆fico.

{RUC}-{TIPO_DOC}-{SERIE}-{CORRELATIVO}.xml
SiglaDescripci贸n
RUCRuc del emisor
TIPO_DOCTipo de Comprobante (Cat谩logo 01)
SERIESerie del comprobante
CORRELATIVOCorrelativo del comprobante

Ejemplos:

  • 20123456789-01-F001-4.xml (Factura)
  • 20123456789-07-F001-5.xml (Nota de cr茅dito relacionada a Factura)
  • 20123456789-03-B001-8.xml (Boleta)
  • 20123456789-07-B001-9.xml (Nota de cr茅dito relacionada a Boleta)
  • 20123456789-09-T001-155.xml (Gu铆a de Remisi贸n)
  • 20123456789-40-P001-222.xml (Percepcion)

Adicionalmente, hay una diferencia con respecto al resumen diario, comunicaciones de baja y resumen de reversiones, que siguen el siguiente formato.

{RUC}-{TIPO}-{FECHA}-{CORRELATIVO}.xml
SiglaDescripci贸n
RUCRuc del emisor
TIPO_DOCTipo documento (RC: Resumen diario, RA: C. de baja, RR: Reversiones )
SERIEFecha generaci贸n del documento (formato: YYYYMMDD)
CORRELATIVOCorrelativo del documento (m谩xima longitud: 5)

Ejemplos:

  • 20123456789-RC-20200930-211.xml (Resumen diario de boletas)
  • 20123456789-RA-20200929-433.xml (Comunicaci贸n de bajas)
  • 20123456789-RR-20201001-11122.xml (Resumen de reversiones)

Zip#

Antes de ejecutar el servicio SOAP, SUNAT necesita que el archivo xml (factura) sea comprimido en formato zip. Para ello podemos utlizar cualquier programa de escritorio (7z, winrar, etc) o en linea de comandos, como el siguiente ejemplo.

zip 20123456789-01-F001-1.zip 20123456789-01-F001-1.xml

El nombre del archivo zip es el mismo que el nombre del xml.

Ejemplo#

En este ejemplo, enviaremos la factura electr贸nica construida en las secciones anteriores, puedes descargarlo desde este enlace.

Debemos tener nuestro comprobante en formato zip: 20123456789-01-F001-1.zip

sendBill#

Para enviar el zip en la trama SOAP, necesitamos codificar el archivo en formato base64.

Podemos usar el siguiente comando:

base64 20123456789-01-F001-1.zip

En la siguiente trama reemplazar el resultado en la marca ZIP_BASE_64, adem谩s estamos incluyendo el nombre del archivo y la cabecera de seguridad donde se incluye las credenciales (clave SOL).

./trama.xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://service.sunat.gob.pe" xmlns:ns2="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<SOAP-ENV:Header>
<ns2:Security>
<ns2:UsernameToken>
<ns2:Username>20123456789MODDATOS</ns2:Username>
<ns2:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">moddatos</ns2:Password>
</ns2:UsernameToken>
</ns2:Security>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<ns1:sendBill>
<fileName>20123456789-01-F001-1.zip</fileName>
<contentFile>ZIP_BASE_64</contentFile>
</ns1:sendBill>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Ahora podemos invocar el servicio SOAP, utilizaremos curl para esta operaci贸n.

curl -X POST -H "Content-Type: text/xml" --data-binary @trama.xml \
https://e-beta.sunat.gob.pe/ol-ti-itcpfegem-beta/billService

El resultado ser谩 el siguiente.

<?xml version="1.0" encoding="UTF-8"?>
<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<soap-env:Header/>
<soap-env:Body>
<br:sendBillResponse xmlns:br="http://service.sunat.gob.pe">
<applicationResponse>ZIP_BASE64_RESPONSE</applicationResponse>
</br:sendBillResponse>
</soap-env:Body>
</soap-env:Envelope>

Guardamos el valor de la marca ZIP_BASE64_RESPONSE en un archivo response.txt, para proceder a decodificarlo y obtener el ZIP que contiene la respuesta.

base64 -d response.txt > result.zip

CDR#

Dentro del archivo zip decodificado (result.zip), encontraremos un archivo xml que representa el CDR (Comprobante de recepci贸n).

R-20123456789-01-F001-123.xml
<?xml version="1.0" encoding="UTF-8"?>
<ar:ApplicationResponse xmlns:ar="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionContent>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<!-- Omitido para ejemplo -->
</Signature>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<cbc:ID>1601506416977</cbc:ID>
<cbc:IssueDate>2020-09-24T11:38:45</cbc:IssueDate>
<cbc:IssueTime>00:00:00</cbc:IssueTime>
<cbc:ResponseDate>2020-09-30</cbc:ResponseDate>
<cbc:ResponseTime>17:53:36</cbc:ResponseTime>
<cac:Signature>
<cbc:ID>SignSUNAT</cbc:ID>
<cac:SignatoryParty>
<cac:PartyIdentification>
<cbc:ID>20131312955</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>SUNAT</cbc:Name>
</cac:PartyName>
</cac:SignatoryParty>
<cac:DigitalSignatureAttachment>
<cac:ExternalReference>
<cbc:URI>#SignSUNAT</cbc:URI>
</cac:ExternalReference>
</cac:DigitalSignatureAttachment>
</cac:Signature>
<cac:SenderParty>
<cac:PartyIdentification>
<cbc:ID>20131312955</cbc:ID>
</cac:PartyIdentification>
</cac:SenderParty>
<cac:ReceiverParty>
<cac:PartyIdentification>
<cbc:ID>20123456789</cbc:ID>
</cac:PartyIdentification>
</cac:ReceiverParty>
<cac:DocumentResponse>
<cac:Response>
<cbc:ReferenceID>F001-123</cbc:ReferenceID>
<cbc:ResponseCode>0</cbc:ResponseCode>
<cbc:Description>La Factura numero F001-123, ha sido aceptada</cbc:Description>
</cac:Response>
<cac:DocumentReference>
<cbc:ID>F001-123</cbc:ID>
</cac:DocumentReference>
<cac:RecipientParty>
<cac:PartyIdentification>
<cbc:ID>6-20000000001</cbc:ID>
</cac:PartyIdentification>
</cac:RecipientParty>
</cac:DocumentResponse>
</ar:ApplicationResponse>

Prestaremos especial atenci贸n al valor del nodo cbc:ResponseCode, que contiene el c贸digo de respuesta, y que nos permitir谩 saber si el comprobante fue aceptado o rechazado.

CodigoDescripcionAcci贸n
0Aceptado-
2000 a 3999RechazadoEmitir nueva factura

En ocasiones el CDR contendr谩 observaciones en el comprobante.

<!-- ... -->
<cbc:ResponseTime>18:38:20</cbc:ResponseTime>
<cbc:Note>4287 - El precio unitario de la operaci贸n que est谩 informando difiere de los c谩lculos realizados en base a la informaci贸n remitida - Error en la linea: 1 (nodo: "/Invoice/cac:InvoiceLine/cac:PricingReference/cac:AlternativeConditionPrice/cbc:PriceAmount", valor:"100")</cbc:Note>
<cbc:Note>4309 - La sumatoria de valor de venta no corresponde a los importes consignados - (nodo: "/Invoice/cac:LegalMonetaryTotal/cbc:LineExtensionAmount", valor:"300.00")</cbc:Note>
<cac:Signature>
<!-- ... -->

Estas observaciones deber谩n ser corregidas en posteriores emisiones.