Configurar capabilities SMP, Peppol Directory y businessCard a través de la API PSB.
La PSB es un Peppol Access Point certificado y un SMP (Service Metadata Publisher). A través de la API se configuran los tipos de documentos que una organización puede recibir, se publican los datos de la empresa en la Peppol Directory y se gestiona la inscripción SMP. Este artículo aborda el contexto técnico y los endpoints API que se utilizan para ello.
Peppol funciona con un modelo de 4 esquinas: el remitente (C1) envía a través de su Access Point (C2) un documento al Access Point del destinatario (C3), que lo reenvía al destinatario (C4). El enrutamiento se basa en dos componentes centrales:
C1 Remitente
C2 Access Point remitente
SML / SMP
C3 Access Point destinatario
C4 Destinatario
SML/SMP lookup
Cuando envía una factura a través de la PSB, esta realiza automáticamente un lookup SML/SMP para encontrar el Access Point correcto del destinatario. Como integrador, no necesita hacerlo usted mismo.
La infraestructura Peppol se desarrolla activamente. Para los integradores que utilizan la API PSB, esto no tiene consecuencias: la PSB gestiona automáticamente los lookups SML/SMP. A continuación se detallan los desarrollos actuales a título informativo.
Internalización SML. OpenPeppol asume la gestión del SML de la Comisión Europea (DG DIGIT). La ventana de migración se abrió el 19 de marzo de 2026. Se aplican dos plazos separados: el plazo para inscripciones SMP es el 31 de mayo de 2026, el periodo de migración para AP Lookup (resolución DNS) se ha ampliado hasta el 31 de agosto de 2026. OpenPeppol discute con la Comisión Europea si el plazo de inscripción SMP también puede ampliarse. Para los integradores API no cambia nada en endpoints o lookups: la PSB gestiona la migración internamente.
Migración CNAME a NAPTR. La migración de registros DNS CNAME a registros NAPTR para lookups SML se completó en marzo de 2026. NAPTR es obligatorio desde el 1 de febrero de 2026. Los antiguos registros CNAME se eliminaron de la red de pruebas SMK (4 de marzo de 2026) y de la red de producción SML (11 de marzo de 2026). Se trata de un cambio DNS interno en la infraestructura Peppol. La PSB ya utiliza NAPTR y no se necesitan ajustes en su integración.
Migración PKI G3. OpenPeppol prepara la transición de los certificados PKI Generation 2 (G2) a Generation 3 (G3). Los certificados G3 se utilizan para la comunicación mutua entre Access Points. El Peppol Testbed admite certificados G2 y G3 desde marzo de 2026, para que los Service Providers puedan probar con anticipación. Aún no se ha publicado una fecha de transición obligatoria. Para los integradores API no cambia nada: la PSB gestiona la renovación de certificados internamente.
Peppol admite tipos de documentos logísticos además de facturas a través de la especificación Peppol Logistics. La versión 1.2 es obligatoria desde el 16 de marzo de 2026. La versión 1.3 es obligatoria desde el 24 de agosto de 2026.
Documentos logísticos admitidos:
Nuevas funciones en la versión 1.3:
La versión 1.3 resuelve los RFC LLC-27 a LLC-35, incluyendo alineamiento de ItemInstance, actualizaciones de no facturación y códigos de subtratamiento para residuos.
Al registrar una party en el SMP de eConnect, se determinan a través de capabilities qué tipos de documentos puede recibir esa party. Cada capability tiene tres estados posibles:
onoffinheritedEl valor recomendado para nuevas inscripciones es inherited, a menos que una party deba desviarse específicamente del estándar.
invoicesselfbillinginvoice_bisv2reviewsinvoiceResponseordersorderOnlyorderAdvancedorderResponseorderResponseAdvancedLas capabilities se configuran a través del endpoint Peppol config:
PUT /api/v1/peppol/config/party/{partyId}
En el cuerpo de la solicitud, especifique el estado deseado por capability. Un ejemplo:
{
"capabilities": {
"invoices": "on",
"selfbilling": "inherited",
"invoiceResponse": "on",
"orderOnly": "on",
"orderAdvanced": "off"
}
}
La Peppol Directory es el registro público de todos los participantes Peppol. Al publicar una businessCard, una party se vuelve localizable en la directory. La businessCard contiene:
La businessCard se publica a través del endpoint Enrollment o a través de la configuración SMP. Tras la publicación, la organización es localizable en directory.peppol.eu.
La API PSB no deriva ningún campo de un registro mercantil vinculado. Independientemente del esquema de identificador (KvK 0106, IVA 9944, OIN 0190, GLN 0088 u otro), tanto names como un address con código de país deben estar explícitamente presentes en la carga útil. Un ejemplo de una businessCard correctamente configurada:
"businessCard": {
"names": {
"value": "eVerbinding, eConnect",
"state": "on",
"description": "Business names."
},
"address": {
"value": "Pelmolenlaan 16A, 3447 GW, Woerden, NL",
"state": "on",
"description": "Geographic information."
},
"emailAddress": {
"value": "techsupport@econnect.eu",
"state": "on",
"description": "Technical contact"
},
"state": "on"
}
El código de país (en el ejemplo anterior, NL al final del campo address) debe incluirse explícitamente.
Both name(s) and country code are required when adding a business cardEste mensaje de error es diagnósticamente inequívoco: la carga útil enviada carece de names, o el address no contiene un código de país. La solución consiste siempre en añadir esos campos explícitamente en la carga útil de la businessCard, y no en modificar otro nivel (party, identificador, capacidades SMP). El mensaje aparece en la práctica con relativa frecuencia en la integración GLN (0088), porque los socios de integración GLN utilizan con menos frecuencia una plantilla que envíe estos campos por defecto. La PSB no presenta un comportamiento distinto para GLN respecto a otros esquemas.
La verificación previa de que un destinatario es accesible en Peppol se realiza por tipo de documento y mediante un endpoint de lookup avanzado:
POST /api/v1/{partyId}/salesInvoice/queryRecipientParty["0106:..."] o { "partyIds": [...], "metaAttributes": {...} }; parámetros opcionales ?preferredDocumentTypeId, ?includeOptionsPOST /api/v1/{partyId}/purchaseOrder/queryRecipientParty?documentFamily=OrderGET /api/v1/peppol/deliveryOption?partyIds=...&documentFamily=...&isCredit=...partyId, documentTypeId, processId, protocol (As2/As4), url, certificateLa respuesta muestra los canales disponibles, el Access Point seleccionado y los tipos de documentos admitidos. Utilice estos endpoints para validar de antemano si un envío tendrá éxito. Están disponibles de forma ilimitada en todos los planes (detección/discovery proactiva de rutas).
Nota: en caso de una discrepancia SML/SMP en el endpoint
deliveryOption, la llamada no falla inmediatamente. No existe manejo fail-fast en producción: la llamada continúa y devuelve un tiempo de espera después de aproximadamente 30 segundos. Tenga esto en cuenta en el manejo de errores de su integración.
En la red Peppol, un participantId en el SML apunta a una sola SMP. Mediante un registro Redirect en la SMP se pueden redirigir combinaciones concretas de tipo de documento e identificador de proceso a una SMP secundaria. Peppol admite un solo nivel de redirección: el destino de una redirección no puede contener a su vez una redirección.
Fuentes alternativas para lookups SMP: peppolautoriteit.nl/discover (NPa), peppol.helger.com y directory.peppol.eu (no completo).
Cada party en el SMP se identifica mediante un identificador con un schemeID. Los esquemas más utilizados:
01060106:1234567801900190:0000000123456789000099449944:NL123456789B010208BE:EN0208:01234567899925BE:VAT9925:BE0835689642 (también BE1xxxxxxxxx es válido desde 2025)00880088:1234567890123La API PSB acepta tanto el schemeID numérico como el código de letras: 9925:BE0835689642 es equivalente a BE:VAT:BE0835689642. Con herramientas de búsqueda externas (como el SMP lookup), deben utilizarse los schemeIDs numéricos oficiales.
Una party puede tener varios identificadores, pero cada factura solo puede contener un EndpointID.
En Bélgica se utilizan dos tipos de identificadores para Peppol. El número de empresa (KBO, schemeID 0208) es el número de identificación principal y obligatorio para la recepción Peppol. La inscripción por número de IVA (schemeID 9925) es opcional, por lo que buscar una organización belga por número de empresa tiene más éxito que por número de IVA.
El número de empresa se puede derivar del número de IVA eliminando el prefijo del código de país (BE). Por ejemplo: el número de IVA BE0835689642 corresponde al número de empresa 0835689642.
Al enviar un documento, la PSB extrae el identificador Peppol del elemento EndpointID en el XML. Este elemento determina a qué destinatario se enruta el documento. Si el EndpointID falta o está incorrectamente rellenado, el documento no es válido y recibe el estado InvoiceSentError.
Un XML incorrecto no se reintenta automáticamente. La corrección corresponde al sistema de origen (el paquete de software que genera la factura), no a la PSB. Verifique previamente a través de queryRecipientParty si el destinatario es accesible en la red Peppol.
Regla de validación NLCIUS que exige que el schemeID del CompanyID tenga el valor 0190 (OIN) cuando el destinatario es una parte pública. En la plataforma, el ID de organización y "Enviar vía" deben usar el mismo tipo de identificador. Una discrepancia produce un error de validación en el documento.
Cuando un proveedor indica que una factura se ha entregado a eConnect como Access Point, pero el destinatario dice no haber recibido nada, el diagnóstico en el lado del destinatario se hace mediante el returnedMessageId.
El returnedMessageId es un ID que eConnect crea en el momento en que el Access Point acepta o rechaza un documento a nivel AS4. Por lo general tiene la forma GUID@econnect.eu. Con este ID, Soporte puede localizar la factura en el sistema y seguir la ruta de procesamiento.
Causas más frecuentes de que un documento se considere "entregado" por el AP emisor y no llegue al destinatario:
Ruta de soporte: con el returnedMessageId, Soporte puede recuperar casi todos los documentos a través de la Management API. Si la búsqueda no tiene éxito, Soporte escala a TechSupport.
Con on activa explícitamente un tipo de documento para una party concreta, con off lo desactiva explícitamente. El valor inherited significa que la party adopta la configuración predeterminada de la organización. Para registros nuevos, inherited es el valor recomendado, salvo que una party deba desviarse de forma específica.
No. La PSB realiza los lookups SML/SMP automáticamente al enviar documentos. Como integrador no necesita interactuar directamente con el SML o la SMP. Los cambios de infraestructura (migración de CNAME a NAPTR o insourcing del SML) tampoco modifican su integración.
Una businessCard no es obligatoria, pero sí recomendable. Sin businessCard, la party sigue siendo alcanzable vía Peppol (el registro SMP está activo), pero no es localizable en el Peppol Directory en directory.peppol.eu. Publique una businessCard para aumentar la visibilidad de su organización.
La API de la PSB no deriva valores de un registro mercantil vinculado. Independientemente del esquema de identificador (cámara de comercio, IVA, OIN, GLN), debe incluir explícitamente names y un address con código de país en cada publicación de businessCard. El mensaje siempre indica un campo names ausente o un address sin código de país. La corrección es completar esos campos en la carga de la businessCard; los cambios a nivel de party, identificador o capability SMP no lo resuelven.
¿Desea automatizar el proceso completo de registro? Consulte el artículo sobre la Enrollment API, que permite configurar registro, capabilities y hooks en una sola llamada API.
Consultar los endpoints SMP