Implement SAT+

OpenData Guías
1

This post proposes a solution to obtain a Full SAT Profile with just one request to a single aggregator site called “SAT All in One”

What is currently obtained from this “Complete SAT Profile”:

“Facturas CFDI 3.2, CFDI 3.3, CFDI 4.0”

	Obtained data: Metadata, XML/JSON

	Expected behavior: Daily downloading of data

“Factura de Retenciones e Información de Pagos Versión 1.0, Versión 2.0”

	Obtained data: Metadata, XML/JSON

	Expected behavior: Daily downloading of data

“Declaraciones Anuales (since 2018)”

	Obtained data: PDF/JSON

	Expected behavior: Monthly download of information

“Declaraciones Mensuales (since 2018)”

	Obtained data: PDF/JSON

	Expected behavior: Monthly download of information

“Opinión de Cumplimiento del SAT”

	Obtained data: PDF/JSON

	Expected behavior: One-time download

“Constancia de Situación Fiscal”

	Obtained data: PDF/JSON

	Expected behavior: One-time download

Functional requirements for the solution

  1. Inserting the Syncfy Widget in the User Interface
  2. Enabling a Webhook for receiving notifications

Inserting the Syncfy Widget in the User Interface

Before proceeding with this section, it is necessary to review in detail the Widget section in the documentation of Syncfy Widget

As reviewed in the documentation, the Syncfy Widget is configurable both in its appearance and in its operation.

For our purposes, it is sufficient to mention that it should be enabled for at least two sections of the User Interface:

  • Registration of SAT credentials**. It is generally done during the user’s onboarding process.
  • Update of SAT credentials**. The user interface should have a section where the user can update the value of his SAT credentials. In this section it is recommended to display to the user an updated status of his SAT synchronization:
    • Result of the last connection
    • Date of last connection
    • Date of last information download

Widget configuration:

 {
	// Set up the token
	token: '<token>',
	enableTestMode : true,
	config: {
    	// Set up the language to use:
   	locale: 'es',
   	entrypoint: {
       	site: "61c12b8cde3c034b3c8b25b1" // !REQUIRED: id_site of SAT All in One
   	},
   	navigation: {
       	oneSiteFlow: true, // !REQUIRED
   	},
	},
};

Widget-less (Optional, not recommended)

Request:

curl --location 'https://sync.paybook.com/v1/jobs' \
--header 'Content-Type: application/json' \
--header 'Cookie: Coyote-2-c264a8c0=7b64a8c0:0' \
--data '{"id_site":"61c12b8cde3c034b3c8b25b1","input":{"rfc":"{{RFC}}","password":"{{CIEC}}"},"id_user":"{{id_user}}" }'

Response:

{
    "rid": "f5652fba-e0f5-41e8-b2c1-db455759dc4c",
    "code": 200,
    "errors": null,
    "status": true,
    "message": null,
    "response": {
        "id_job_uuid": "648cc12358b1a5697b06a41f",
        "id_job": "648cc12358b1a5697b06a41e",
        "ws": "wss://sync.paybook.com/v1/status/648cc12358b1a5697b06a41e",
        "status": "https://sync.paybook.com/v1/jobs/648cc12358b1a5697b06a41e/status",
        "twofa": "https://sync.paybook.com/v1/jobs/648cc12358b1a5697b06a41e/twofa"
    }
}

Enabling a Webhook for receiving notifications

Webhooks allow you to receive notifications from the SAT All In One process, by correctly processing your messages the solution will be able to determine if an RFC has connected properly or has encountered a problem.

A Webhook must be registered to receive notifications from all users linked to the solution, the suggested practice is to register a single general webhook , if you already have a registered webhook, it can be used for this purpose and only register the missing events.

Listed below are the events, their description and the SAT information to which they are related.

Event Description
credential_create Notification of the creation of a credential, i.e. access to the site. It is only received for credentials that have been created for the first time for a user.
credential_update Notification of a credential update. It is received when the connection is initiated and when the connection to the site is terminated.
refresh Notification to inform that a credential has new or updated information.
documents_completed Notification to inform that documents are ready for download.
Event/Site CIEC CIEC Retenciones Declaraciones Anuales/Mensuales Constancia de Situación Fiscal Opinión de Cumplimiento
credential.create :white_check_mark: :white_check_mark: :white_check_mark:
credential.update :white_check_mark: :white_check_mark: :white_check_mark:
credential.refresh :white_check_mark: :white_check_mark: :white_check_mark:
documents.completed :white_check_mark: :white_check_mark:
documents.success :white_check_mark: :white_check_mark:
documents.fail :white_check_mark: :white_check_mark:
id_site Site name
— CIEC
— CIEC Retenciones
— Declaraciones Anuales
— Declaraciones Mensuales
— Constancia de Situacion fiscal
— Opinion de cumplimiento

The documents.success and documents.fail events are only available in version 3 of the Webhooks, which are created from the Syncfy.com dashboar in the webhooks section.

Note: The Syncfy API should not be used as a database, it is only the source of the data. To build an optimal connection to SAT All in One and provide the best experience to the User it is necessary to persist in the solution’s database all the information delivered by the Syncy API and every time the User Interface requires it, it should be delivered through the Backend using the queries to the solution’s DB Server.

How it works:

image

Webhook notifications:

credentials.created

{
    "rid": "c53b1fcb-e112-465c-ad3e-8b64cf2f602c",
    "events": [
        {
            "header": {
                "event": {
                    "eid": "6ff4da49-4193-4ee0-8e9e-7415b7fcb9cb",
                    "name": "credentials.created",
                    "at": "2023-06-16 19:06:18.944575+0000",
                    "version": "3.1"
                },
                "user": {
                    "id_user": "648a053b59f043380d473be3",
                    "id_external": "20230614-DEMO",
                    "id_environment": "574894bf7848066d138b4571"
                }
            },
            "payload": {
                "event": "credential_create",
                "id_job": "648cb2a9718d6c796e4091c1",
                "id_job_uuid": "648cb2a9718d6c796e4091c2",
                "id_credential": "648cb2a99ca1b91b0a141391",
                "id_user": "648a053b59f043380d473be3",
                "id_external": "20230614-DEMO",
                "id_site": "56cf5728784806f72b8b456f",
                "id_site_organization": "56cf4ff5784806152c8b4568",
                "id_site_organization_type": "56cf4f5b784806cf028b4569",
                "is_executing": 1,
                "endpoints": {
                    "credential": [
                        "/v1/credentials/648cb2a99ca1b91b0a141391"
                    ]
                }
            }
        }
    ]
}

credentials.updated

{
    "rid": "c2199b6a-7355-4dc8-98cf-a18305a3727f",
    "events": [
        {
            "header": {
                "event": {
                    "eid": "46346c7b-f990-49e7-96d9-0d33f7406b4f",
                    "name": "credentials.updated",
                    "at": "2023-06-16 19:06:23.961107+0000",
                    "version": "3.1"
                },
                "user": {
                    "id_user": "648a053b59f043380d473be3",
                    "id_external": "20230614-DEMO",
                    "id_environment": "574894bf7848066d138b4571"
                }
            },
            "payload": {
                "event": "credential_update",
                "id_job": "648cb2a9718d6c796e4091c1",
                "id_job_uuid": "648cb2a9718d6c796e4091c2",
                "id_credential": "648cb2a99ca1b91b0a141391",
                "id_user": "648a053b59f043380d473be3",
                "id_external": "20230614-DEMO",
                "id_site": "56cf5728784806f72b8b456f",
                "id_site_organization": "56cf4ff5784806152c8b4568",
                "id_site_organization_type": "56cf4f5b784806cf028b4569",
                "is_executing": 0,
                "endpoints": {
                    "credential": [
                        "/v1/credentials/648cb2a99ca1b91b0a141391"
                    ]
                }
            }
        }
    ]
}

credentials.refreshed

{
    "rid": "d5a7fa51-e661-433b-a040-5286058f3605",
    "events": [
        {
            "header": {
                "event": {
                    "eid": "2709cf46-0ebd-4856-ac26-421b378ff571",
                    "name": "credentials.refreshed",
                    "at": "2023-06-16 19:06:42.721561+0000",
                    "version": "3.1"
                },
                "user": {
                    "id_user": "648a053b59f043380d473be3",
                    "id_external": "20230614-DEMO",
                    "id_environment": "574894bf7848066d138b4571"
                }
            },
            "payload": {
                "event": "refresh",
                "id_job": "648cb2aba5e16209404ee97c",
                "id_job_type": "57884c49784806f0768b4568",
                "id_job_uuid": "648cb2aba5e16209404ee97b",
                "id_job_uuid_type": "57884c49784806f0768b4568",
                "id_credential": "648cb2aa8c7a0b6c2b2e6694",
                "id_user": "648a053b59f043380d473be3",
                "id_external": "20230614-DEMO",
                "id_site": "59aefe28056f29793a58c091",
                "id_site_organization": "56cf4ff5784806152c8b4568",
                "id_site_organization_type": "56cf4f5b784806cf028b4569",
                "endpoints": {
                    "credential": [
                        "/v1/credentials/648cb2aa8c7a0b6c2b2e6694"
                    ],
                    "accounts": [
                        "/v1/accounts?id_credential=648cb2aa8c7a0b6c2b2e6694&dt_refresh_from=1684213883&dt_refresh_to=1684213915&limit=5000&skip=0&wbhk=1"
                    ],
                    "attachments": [
                        "/v1/attachments/export?id_credential=648cb2aa8c7a0b6c2b2e6694&dt_refresh_from=1684213883&dt_refresh_to=1684213915&limit=5000&skip=0&wbhk=1"
                    ],
                    "transactions": [
                        "/v1/transactions?id_credential=648cb2aa8c7a0b6c2b2e6694&dt_refresh_from=1684213883&dt_refresh_to=1684213915&limit=5000&skip=0&wbhk=1"
                    ]
                }
            }
        }
    ]
}

documents.completed

{
    "rid": "8653a68e-0e3f-4ab1-97e0-c773be77dfb4",
    "events": [
        {
            "header": {
                "event": {
                    "eid": "91f5f406-cb4a-417c-8dc1-fde7482ad27a",
                    "name": "documents.completed",
                    "at": "2023-06-16 19:06:57.591579+0000",
                    "version": "3.1"
                },
                "user": {
                    "id_user": "648a053b59f043380d473be3",
                    "id_external": "20230614-DEMO",
                    "id_environment": "574894bf7848066d138b4571"
                }
            },
            "payload": {
                "id_job": "648cb2ab199e4b39654a9d20",
                "id_job_uuid": "648cb2ab199e4b39654a9d21",
                "id_site": "59aefe28056f29793a58c092",
                "id_site_organization": "56cf4ff5784806152c8b4568",
                "id_site_organization_type": "56cf4f5b784806cf028b4569",
                "endpoints": [
                    "/v1/documents?id_job_webhook=648cb2d190b1bf61cc50b3ba"
                ]
            }
        }
    ]
}

documents.success

{
    "rid": "0dd264d9-323e-43ff-9182-af3c895707f0",
    "events": [
        {
            "header": {
                "event": {
                    "eid": "b1c38530-661f-41ea-911a-9fbd9b197c3e",
                    "name": "documents.success",
                    "at": "2023-06-16 19:06:57.596733+0000",
                    "version": "3.1"
                },
                "user": {
                    "id_user": "648a053b59f043380d473be3",
                    "id_external": "20230614-DEMO",
                    "id_environment": "574894bf7848066d138b4571"
                }
            },
            "payload": {
                "id_job": "648cb2ab199e4b39654a9d20",
                "id_job_uuid": "648cb2ab199e4b39654a9d21",
                "id_site": "59aefe28056f29793a58c092",
                "id_site_organization": "56cf4ff5784806152c8b4568",
                "id_site_organization_type": "56cf4f5b784806cf028b4569",
                "endpoints": [
                    "/v1/documents?id_job_webhook=648cb2d190b1bf61cc50b3bd"
                ]
            }
        }
    ]
}