Link Search Menu Expand Document

Comunicaci贸n con FACeB2B

Facturae-PHP permite establecer comunicaci贸n directa sin salir de la librer铆a con los servicios web de FACeB2B para enviar y recibir facturas entre empresas del sector privado.

Prerequisitos

Para poder usar los servicios web de FACeB2B el proceso es un poco m谩s complicado que con FACe, ya que se requiere de varios pasos:

  1. Da de alta tu empresa en DIRe usando el certificado expedido por la FNMT para tu persona f铆sica. Aseg煤rate de que activas la empresa.
  2. A continuaci贸n, asocia tu empresa con FACeB2B autentic谩ndote como 鈥淐liente鈥 con el mismo certificado de antes.
  3. Tambi茅n desde FACeB2B, registra tu empresa como ESF. No hace falta que marques la casilla de gestionar facturas de terceros.
  4. Crea una nueva plataforma de facturaci贸n y sube la clave p煤blica del certificado que utilizar谩s para comunicarte con los Web Services. Puede ser la clave p煤blica del certificado que hemos estado usando hasta ahora.
  5. Asocia las unidades DIRe desde FACeB2B (pesta帽a 鈥淎lta de clientes鈥) a la plataforma que acabas de crear.

Cliente de FACeB2B

El uso de FACeB2B desde Facturae-PHP es extremadamente sencillo:

use josemmo\Facturae\Face\Faceb2bClient;

$face = new Faceb2bClient("clave_publica.pem", "clave_privada.pem", "passphrase");

Al igual que al firmar una factura electr贸nica, puedes usar un solo archivo .pfx en vez de un par .pem:

$face = new Faceb2bClient("certificado.pfx", null, "passphrase");

Por defecto, Faceb2bClient se comunica con el entorno de producci贸n de FACeB2B. Para usar el entorno de pruebas (staging) puedes utilizar el siguiente m茅todo:

$face->setProduction(false);

Todas las llamadas a FACeB2B desde Faceb2bClient devuelven un objeto SimpleXMLElement. Consulta el manual de PHP para m谩s informaci贸n.


Listado de m茅todos

A continuaci贸n se incluyen los m茅todos de Faceb2bClient para llamar al servicio web FACeB2B junto a una vista previa en JSON de la respuesta que devuelven.

$face->sendInvoice(:invoice, [:attachment])

Env铆a una factura v谩lida a FACeB2B y un archivo adjunto (solo uno, a diferencia de FACe que admite varios) de forma opcional. Tanto la factura como el adjunto deben ser una instancia v谩lida de FacturaeFile.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    },
    "invoiceDetail": {
        "registryNumber": "201801122333",
        "invoiceNumber": "123",
        "invoiceSeriesCode": "FAC201804",
        "receivingUnit": {
            "code": "ESB999999990000",
            "name": "Nombre de la unidad"
        },
        "additionalAdministrativeCentres": {},
        "sellerTaxIdentification": "A00000000",
        "amount": "1.00",
        "currency": "EUR",
        "issueDate": "2018-06-17T00:00:00+02:00",
        "receptionDate": "2018-07-04T19:41:03+02:00",
        "statusInfo": {
            "status": {
                "code": "1200",
                "name": "Registrada",
                "description": "Registrada"
            },
            "modificationDate": "2018-07-04T19:41:10+02:00"
        },
        "cancellationInfo": {}
    }
}

$face->getInvoiceDetails(:regId)

Devuelve los datos de una factura a partir de su n煤mero de registro.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    },
    "invoiceDetail": {
        "registryNumber": "201801122333",
        "invoiceNumber": "123",
        "invoiceSeriesCode": "FAC201804",
        "receivingUnit": {
            "code": "ESB999999990000",
            "name": "Nombre de la unidad"
        },
        "additionalAdministrativeCentres": {},
        "sellerTaxIdentification": "A00000000",
        "amount": "1.00",
        "currency": "EUR",
        "issueDate": "2018-06-17T00:00:00+02:00",
        "receptionDate": "2018-07-04T19:41:03+02:00",
        "statusInfo": {
            "status": {
                "code": "1200",
                "name": "Registrada",
                "description": "Registrada"
            },
            "modificationDate": "2018-07-04T19:41:10+02:00"
        },
        "cancellationInfo": {}
    }
}

$face->requestInvoiceCancellation(:regId, :reason, [:comment])

Solicita la cancelaci贸n de una factura a partir de su n煤mero de registro, debiendo indicarse un motivo para la cancelaci贸n (generalmente C001) y opcionalmente un comentario (cadena de texto).

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    }
}

$face->getRegisteredInvoices([:receivingUnit])

Devuelve el listado de facturas (hasta un m谩ximo de 500) registradas en FACeB2B gestionadas por la ESF asociada al certificado usado en las comunicaciones con el Web Service. Opcionalmente se puede indicar el c贸digo de una unidad receptora para filtrar facturas.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    },
    "newRegisteredInvoices": {
        "registryNumber": "201801122333"
    }
}

$face->getInvoiceCancellations()

Devuelve el listado de facturas canceladas gestionadas por la ESF asociada al certificado usado en las comunicaciones con el Web Service.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    },
    "invoiceCancellationRequests": {
        "registryNumber": "201801122333"
    }
}

$face->downloadInvoice(:regId, [:validate])

Devuelve los datos de una factura y el archivo original codificado en Base64 a partir de su n煤mero de registro. Por defecto tambi茅n se devuelve un informe (reportFile) con la validez de la misma, salvo que se pase false como valor del segundo par谩metro.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    },
    "invoiceDetail": {
        "registryNumber": "201801122333",
        "invoiceNumber": "123",
        "invoiceSeriesCode": "FAC201804",
        "receivingUnit": {
            "code": "ESB999999990000",
            "name": "Nombre de la unidad"
        },
        "additionalAdministrativeCentres": {},
        "sellerTaxIdentification": "A00000000",
        "amount": "1.00",
        "currency": "EUR",
        "issueDate": "2018-06-17T00:00:00+02:00",
        "receptionDate": "2018-07-04T19:41:03+02:00",
        "statusInfo": {
            "status": {
                "code": "1200",
                "name": "Registrada",
                "description": "Registrada"
            },
            "modificationDate": "2018-07-04T19:41:10+02:00"
        },
        "cancellationInfo": {}
    },
    "invoiceFile": {
        "content": "PD94bWwg...cmFlPg==",
        "name": "factura-de-prueba.xsig",
        "mime": "text/xml"
    },
    "reportFile": {
        "content": "PD94bWwg...cnQ+Cg==",
        "name": "201801122333.xml",
        "mime": "text/xml"
    }
}

$face->confirmInvoiceDownload(:regId)

Notifica a FACeB2B de la descarga de una factura a partir de su n煤mero de registro.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    }
}

$face->rejectInvoice(:regId, :reason, [:comment])

Rechaza la recepci贸n de una factura a partir de su n煤mero de registro, debiendo indicarse un motivo para el rechazo (generalmente R001) y opcionalmente un comentario (cadena de texto).

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    }
}

$face->markInvoiceAsPaid(:regId)

Marca una factura como pagada a partir de su n煤mero de registro.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    }
}

$face->acceptInvoiceCancellation(:regId)

Acepta la cancelaci贸n de una factura a partir de su n煤mero de registro.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    }
}

$face->rejectInvoiceCancellation(:regId, :comment)

Acepta la cancelaci贸n de una factura a partir de su n煤mero de registro. Debe indicarse un comentario sobre el motivo del rechazo de la petici贸n de cancelaci贸n.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    }
}

$face->validateInvoiceSignature(:regId, :invoice)

Valida la autenticidad de una factura a partir de su n煤mero de registro y de su firma en XML. Este m茅todo se utiliza para que terceros puedan comprobar la autor铆a e integridad de una factura sin disponer de los contenidos de la misma, solo teniendo su firma XAdES en XML y su ID de registro.

{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    },
    "reportFile": {
        "content": "PD94bWwg...cnQ+Cg==",
        "name": "201801122333.xml",
        "mime": "text/xml"
    }
}

$face->getCodes([:type])

Devuelve el listado de c贸digos de negocio que emplea el Web Service. Opcionalmente se pueden obtener solo los c贸digos de un determinado tipo. Los tipos v谩lidos (seg煤n la documentaci贸n oficial de FACeB2B) son:

  • invoiceStatus
  • rejectionReason
  • cancellationReason
{
    "resultStatus": {
        "code": "0",
        "message": "Success",
        "detail": {},
        "trackingCode": {}
    },
    "codes": {
        "item": [
            {
                "code": "1200",
                "name": "Registrada en broker FACeB2B",
                "description": "La factura ha sido registrada en el registro electr贸nico REC"
            },
            [...]
        ]
    }
}