Clients

HTTP header parameters

Authorization (string): API authorisation. Example: Bearer {token}

Base URL

https://api.saltra.es/api/v4/customer

Get clients

Parameters

search optional (string): Search field; you can search by email, name, CIF, etc.
page optional (integer): Current page.
perPage optional (integer): Number of records per page (maximum 50; asking for more returns 50).

GET /

{
  "search": "B188888888",
  "page": 1,
  "perPage": 20
}

Response

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "data": [
      {
        "id": 9999,
        "name": "USER CUSTOMER",
        "active": 1,
        "access": {
          "email": "test@example.es"
        },
        "profile": {
          "identificacion": 1,
          "dni": "B188888888",
          "razon_social": "CUSTOMER",
          "codigo_postal": "01005",
          "direccion": "CALLE",
          "country": 724,
          "account": [
            {
              "id": 9999,
              "activa": 1,
              "alias": "CUSTOMER",
              "convenio_colectivo": "60888888888888",
              "cuenta": "28199993333",
              "regimen": "0111",
            }
          ],
          "parameters": {
            "representativeData": {
                "doc": "77056403D",
                "name": "JOSE",
                "surname": "APELLIDO",
                "job_position": "ADMINISTRADOR"
            }
          }
        }
      }
    ],
    "pagination": {
      "page": 1,
      "lastPage": 1,
      "perPage": 50,
      "total": 2
    }
  }
}

Save a client

Parameters

name (string) : Client name. Required. Maximum 255 characters.
access (object) : Access credentials. Required.
- email (string) : Email address. Required. Maximum 50 characters; it must not already exist in Saltra.
- password optional (string) : Password, at least 4 characters. If you do not send it, the client receives an email link to create it (unless not_notify = 1).
- password_confirmation (string) : Password confirmation. Required only if you send password.
not_notify optional (boolean): Do NOT notify the client that the user was created. Possible values: 1 = do NOT notify the client, 0 = notify the client.
sub_activa optional (boolean): Client access to the Saltra platform. With 0 the company is created without access and no email is sent to it.
alternativo optional (string or array): Alternative notification emails, comma-separated or as a list (100 characters at most in total).
profile (object) : Client profile data. Required.
- dni (string) : Company CIF. Required. Maximum 10 characters.
- razon_social (string) : Registered name of the company. Required. Maximum 80 characters.
- codigo_postal optional (string) : Postcode. Maximum 5 characters.
- direccion optional (string) : Address. Maximum 190 characters.
- external_id optional (string) : The company's identifier in your system. Maximum 100 characters.
- account (array) : Contribution accounts. Required, at least one account.
  - regimen (string) : Scheme of the account, 4 digits (e.g. 0111). Required.
  - cuenta (string) : Contribution account code, 11 digits. Required.
  - alias (string) : Account alias. Required. Maximum 30 characters.
  - convenio_colectivo optional (string) : Collective agreement. Maximum 15 characters.
- parameters optional (object) : Client parameters.
  - representativeData optional (object) : Details of the company's legal representative. If you send it, its four fields are required.
    - doc (string) : Representative's identity document. Maximum 11 characters.
    - name (string) : Representative's first name. Maximum 80 characters.
    - surname (string) : Representative's surname. Maximum 80 characters.
    - job_position (string) : Representative's job position. Maximum 50 characters.

POST /

{
    "name": "NOMBRE DE LA EMPRESA",
    "access": {
        "email": "test@example.es",
        "password": "123456",
        "password_confirmation": "123456"
    },
    "not_notify": 1,
    "profile": {
        "dni": "B46469763",
        "razon_social": "NOMBRE DE LA EMPRESA",
        "codigo_postal": "01005",
        "direccion": "calle alava...",
        "external_id": "ERP-000123",
        "account": [
            {
                "alias": "Regimen de madrid",
                "cuenta": "28148369999",
                "regimen": "0111"
            },
            {
                "alias": "Regimen de prueba",
                "cuenta": "13119940999",
                "regimen": "0112"
            }
        ],
        "parameters": {
            "representativeData": {
                "doc": "77056403D",
                "name": "JOSE",
                "surname": "APELLIDO",
                "job_position": "ADMINISTRADOR"
            }
        }
    }
}

Minimal request, with the required fields only:

POST / (mínimo)

{
    "name": "NOMBRE DE LA EMPRESA",
    "access": {
        "email": "test@example.es"
    },
    "profile": {
        "dni": "B46469763",
        "razon_social": "NOMBRE DE LA EMPRESA",
        "account": [
            {
                "alias": "Regimen de madrid",
                "cuenta": "28148369999",
                "regimen": "0111"
            }
        ]
    }
}

If you already have a company with that CIF, no new one is created: the contribution accounts it is missing are added to it and the response returns that company, with a message explaining so.

Response

Respuesta

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 9999,
    "name": "NOMBRE DE LA EMPRESA",
    "access": {
        "email": "test@example.es"
    },
    "...": "..."
  }
}

If a required field is missing or a field is invalid, the response is 422 with the per-field detail in errors:

Respuesta 422

{
  "success": false,
  "status": 422,
  "message": "Error de validación",
  "errors": {
    "profile.account": ["Debe haber al menos una Cuenta de Cotización asociada al cliente"],
    "profile.parameters.representativeData.job_position": ["El campo Cargo del Representante Legal es obligatorio"]
  }
}

Delete a client

Parameters

id (integer): Client ID.

DELETE /{customerID}

customerID

Response

Respuesta

{
  "success": true,
  "message": "OK"
}

Deactivate a client

Parameters

id (integer): Client ID.
active (integer) : Possible values:
- true: Activate
- false: Deactivate

PUT /{customerID}/activate

{
  "active": false,
}

Response

Respuesta

{
  "success": true,
  "message": "OK"
}