Pull your Oficina Virtual CCSS planilla into your systems

What you can build on the Oficina Virtual

• Get the planilla invoice for a period

  Build this

  Reads the factura (invoice) for one billing period of your planilla, with the amount due and the payment date the Oficina Virtual shows.

  Takes

  Billing period

  Returns

  Employer, period, amount due, currency, payment date, paid or pending

• Get the billing reports for a period

  Build this

  Generates the reports under Generar los reportes de la facturación (billing reports) for one period and reads them worker by worker.

  Takes

  Billing period

  Returns

  Worker, ID number, salary reported, occupation, insurance class, amount billed

• Check earlier Grandes Clientes uploads

  Build this

  Reads Consulta Cargas Previas (earlier uploads) for planilla files sent in the Grandes Clientes format, with how each one was validated.

  Takes

  Billing period (optional)

  Returns

  File name, upload date, period, validation result, errors

• Add a new worker to the planilla

  Build this

  Uses Incluir un nuevo trabajador (add a new worker) to put a hire on your planilla with salary, occupation, jornada and clase de seguro.

  Takes

  ID number, name, start date, salary, occupation, jornada, insurance class

  Returns

  ID number, name, start date, salary, confirmation

Automate the Oficina Virtual with a workflow

A workflow runs your methods as one process, with nobody at the screen. A schedule or a call from your own system starts it, the steps run in order, and the result arrives in your inbox or in the systems you already use.

• Planilla invoice and payment date, to accounting

  Build this

  Starts

  Every month on the 16th at 8:00, Costa Rica time

  Step 1

  Get the planilla invoice for the latest billing period.

  Step 2

  Stop when the invoice is already paid.

  Step 3

  Post the period, amount due and payment date to your accounting system's webhook.

• Billing reports: workers whose salary or class changed

  Build this

  Starts

  When your payroll system calls the workflow's webhook with a billing period

  Step 1

  Get the billing reports for the period your system sends.

  Step 2

  Keep the workers whose salary or insurance class changed since the last run.

  Step 3

  Email you the list with ID number, salary reported and amount billed.

• New results on your Grandes Clientes uploads

  Build this

  Starts

  Every weekday at 7:00, Costa Rica time

  Step 1

  Check the earlier Grandes Clientes uploads for the latest billing period.

  Step 2

  Keep the files that were not there on the last run.

  Step 3

  Email you each file's name, upload date, validation result and errors.

You can run a workflow by hand on every plan, Free included. Schedules and webhook triggers come with the paid plans, from $29 a month.

Once built, one call from your code

Once you have built a method, it is one POST to /v1/runs from your backend, or a tool an AI agent calls over MCP. This is what “Get the planilla invoice for a period” would look like.

curl https://api.fous.com/v1/runs \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "aissfa.ccss.sa.cr/get_planilla_invoice",
    "input": {
      "period": "2026-10"
    }
  }'

{
  "status": "completed",
  "data": {
    "employer": "Acme Servicios S.A.",
    "period": "2026-10",
    "amount_due": 2864310,
    "currency": "CRC",
    "payment_date": "2026-11-18",
    "status": "pending"
  }
}

An example with invented data, not a ready-made endpoint. The method exists in your organization once you build it, and its name, inputs and fields follow your request.

The Oficina Virtual’s own options

The CCSS's employer pages describe no API. Employers file the planilla in the Oficina Virtual worker by worker, or upload it as a file in the Grandes Clientes format, which the Oficina Virtual validates itself. The CCSSmóvil app uses the same account to consult and pay pending invoices.

Read on November 12, 2026: CCSS: information and services for employers, CCSSmóvil, Oficina Virtual CCSS sign-in.

Signing in to the Oficina Virtual

The Oficina Virtual signs you in with your Usuario (user name) and password, or with a Certificado digital (digital certificate). A forgotten password is regenerated with Olvidó su contraseña, and CCSSmóvil takes the same account. With Fous you sign in once through the Oficina Virtual's own sign-in with your own account: the login is sealed with AES-256 and never returned by the API or written to logs.

Worth knowing

A fixed filing window every month

The planilla is presented from the 26th of each month to the fourth business day of the next. Employers filing as Grandes Clientes have until the third business day.

Check the payment date from the 16th

The CCSS tells employers to verify their payment date in the Oficina Virtual from the 16th to the 20th of each month. A monthly workflow can read it on the 16th.

Low salaries are raised to the BMC

Salaries below ¢346,789.00 for SEM and ¢324,590.00 for IVM are adjusted to the base mínima contributiva (BMC), so the amount billed can differ from the salary you reported.

The IVM rate is 11.66% until 2028

From January 2026 to December 2028 the IVM contribution is 11.66%. Keep it in mind when you compare the amount billed with your own payroll.

More in Government: Latin America

• Mis Comprobantes
• Facturación Electrónica DIAN
• Simplificación Registral
• ARCA - servicios con Clave Fiscal
• Portal Empresarial INFONAVIT
• SIFERE Web
• Declaración en Línea (F.931)
• AFPnet
• ARBA
• SEACE
• SECOP II
• BPS Servicios en Línea
• IESS - Portal de Empleadores
• SUIR
• Previred
• Aportes en Línea
• SOI
• SIPARE
• DGI Servicios en Línea
• e-Tax 2.0
• Agencia Virtual SAT
• Oficina Virtual DGII
• Portal del SAT (Factura Electrónica)
• SII (Mi SII)
• SRI en Línea
• SUNAT Operaciones en Línea (SOL)
• TRIBU-CR
• Declaraciones y Pagos (SAT)
• DIAN MUISCA

Other industries: EmaraTax, e-ΕΦΚΑ, Planning Portal, Sunshine 811, HSBC UK for Intermediaries, FLAG.