Gestión de planes y suscripciones

En este apartado se abordan los aspectos más destacables sobre la creación, consulta de datos e integración de suscripciones así como los planes de los que dispone el dominio.

Planes (Plan)

Recuperar listado de planes

Devuelve un listado de planes pertenecientes al dominio del usuario conectado.

https://developers.gadaca.com/#api-Plans-PlanListGet

Ejemplo de respuesta:

HTTP/1.1 200 OK
{
   "data": [
        {
            "object": "Plan",
            "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "uuid": "123e4567-e89b-12d3-a456-426614174000",
            "apportionment_type_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "code": "anual",
            "currency_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "description": "Plan ilimitado",
            "domain_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "duration": 12,
            "duration_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "free_tier_duration": 1,
            "free_tier_duration_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "is_autorenewable": true,
            "is_copayment_individual": false,
            "is_copayment_invoiced_instantly": false,
            "is_ended_by_promotional_code": false,
            "is_holder_signature_required": false,
            "is_invoice_generable": true,
            "is_payment_automatic": true,
            "is_public": true,
            "is_signature_needed_to_invoice": false,
            "level": 5,
            "name": "Anual",
            "permanence": 2,
            "permanence_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "price_quota": 9.99,
            "price_quota_per_user": 1.99,
            "price_upfront": 24.99,
            "price_upfront_per_user": 0,
            "status_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "users_limit": 7,
            "users_age_limit": 18,
            "users_over_age_limit": 2,
            "apportionment_type": {
                "data": {
                    "object": "Category",
                    "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
                    "code": "monthly",
                    "name": "Mensual"
                }
            },
            "currency": {
                "data": {
                    "object": "Currency",
                    "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
                    "code": "EUR",
                    "name": "Euro",
                    "minor_unit": 2,
                }
            },
            "duration_unit": {
                "data": {
                    "object": "Category",
                    "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
                    "code": "months",
                    "name": "Meses"
                }
            },
            "free_tier_duration_unit": {
                "data": {
                    "object": "Category",
                    "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
                    "code": "months",
                    "name": "Meses"
                }
            },
            "permanence_unit": {
                "data": {
                    "object": "Category",
                    "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
                    "code": "months",
                    "name": "Meses"
                }
            },
            "status": {
                "data": {
                    "object": "Category",
                    "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
                    "code": "active",
                    "name": "Activo"
                }
            },
            "created_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "updated_at": {
                "date": "2017-06-26 21:00:02.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 2,
            "count": 2,
            "per_page": 20,
            "current_page": 1,
            "total_pages": 1,
            "links": []
        }
    }
}

Subscripciones (Subscription)

A continuación, se especificarán todas los pasos para crear suscripciones y actuar sobre las mismas.

Objeto subscripción

Ejemplo de objeto de respuesta de un objeto de tipo suscripción.

HTTP/1.1 200 OK
{
   "data": {
        "object": "Subscription",
        "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "apportionment_type_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "begin_at": {
            "date": "2017-04-09 12:02:46.000000",
            "timezone_type": 3,
            "timezone": "Europe/Madrid"
        },
        "billed_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "code": "HOM3HDB100000001",
        "commercial_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "currency_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "distributor_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "domain_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "duration": 5,
        "duration_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "end_at": {
            "date": "2017-04-09 12:02:46.000000",
            "timezone_type": 3,
            "timezone": "Europe/Madrid"
        },
        "external_id": "9192332234234-n23423",
        "free_tier_begin_at": {
            "date": "2017-04-09 12:02:46.000000",
            "timezone_type": 3,
            "timezone": "Europe/Madrid"
        },
        "free_tier_duration": 5,
        "free_tier_duration_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "free_tier_end_at": {
            "date": "2017-04-09 12:02:46.000000",
            "timezone_type": 3,
            "timezone": "Europe/Madrid"
        },
        "holder_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "is_autorenewable": true,
        "is_copayment_individual": true,
        "is_copayment_invoiced_instantly": false,
        "is_ended_by_promotional_code": true,
        "is_holder_signature_required": true,
        "is_invoice_generable": true,
        "is_payment_automatic": true,
        "level": 5,
        "name": "Unlimited",
        "permanence": 5,
        "permanence_end_at": {
            "date": "2017-04-09 12:02:46.000000",
            "timezone_type": 3,
            "timezone": "Europe/Madrid"
        },
        "permanence_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "plan_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "policy_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "price_quota": 23.12,
        "price_quota_per_user": 12.54,
        "price_upfront": 8.76,
        "price_upfront_per_user": 3.15,
        "promotional_code_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "status_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
        "users_limit": 6,
        "users_age_limit": 18,
        "users_over_age_limit": 2,
        "apportionment_type": {
            "data": {
                "object": "Category",
                "code": "monthly"
            }
        },
        "duration_unit": {
            "data": {
                "object": "Category",
                "code": "months"
            }
        },
        "free_tier_duration_unit": {
            "data": {
                "object": "Category",
                "code": "days"
            }
        },
        "permanence_unit": {
            "data": {
                "object": "Category",
                "code": "months"
            }
        },
        "status": {
            "data": {
                "object": "Category",
                "code": "active"
            }
        },
        "created_at": {
            "date": "2017-04-09 12:02:46.000000",
            "timezone_type": 3,
            "timezone": "Europe/Madrid"
        },
        "updated_at": {
            "date": "2017-06-26 21:00:02.000000",
            "timezone_type": 3,
            "timezone": "Europe/Madrid"
        }
    }
}

Crear suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionPost

Campos importantes para la creación de una suscripción:

• code: (opcional) código que asignar a la suscripción, puede ser utilizado para almacenar el código de contrato del sistema a integrar
• external_id: (opcional) identificador del contrato en el sistema externo
• commercial_id: (obligatorio si el usuario que hace la petición no es el holder) Identificador del comercial del plan, se proporcionará.
• distributor_id: (obligatorio con commercial_id) identificador del distribuidor del plan, se proporcionará.
• holder_id: identificador del propietario de la suscripción. debe de ser un usuario perteneciente al dominio. Revisar sección de usuarios.
• payment_method: Objeto de tipo payment_method el cuál se creará y asignará a la suscripción
• payment_method_id: Identificador de un método de pago previamente creado y asignado a un usuario.
• plan_id: identificador del plan a que asociar la suscripción.
• users_ids: campo opcional donde se pueden enviar los identificadores de los usuarios que van a ser beneficiarios de la suscripción. Debe respetar los límtes de usuarios establecidos por el plan.
• promotional_code: Código promocional obligatorio en caso de que el plan no sea público.
• confirmed: Indica si la subscripción se debe autoconfirmar e iniciar. Si se envía, se regirá por las mismas reglas de validación que SubscriptionConfirmPut.

Se retorna un objeto de tipo suscripción.

Modificar suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionPut

Se modifica la suscripción utilizando el identificado de la misma.

Retorna un objeto de tipo suscripción.

Confirmar y activar suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionConfirmPut

Se confirma y activa una suscripción utilizando el identificador de la misma.

Retorna un objeto de tipo suscripción.

Cancelar suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionCancelPut

Se cancela una suscripción utilizando el identificador de la misma. Cancela la suscripción de diferentes formas dependiendo del momento histórico en el que se encuentre

Retorna un objeto de tipo suscripción.

Dar de baja suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionUnsubscribePut

Se da de baja una suscripción utilizando el identificador de la misma. Da de baja la suscripción. Este endpoint establece una fecha de fin de la suscripción al último día de del ciclo actual de facturación a menos que se envíe el parámetro "unsubscribe_today".

Retorna un objeto de tipo suscripción.

Dar de baja suscripción por código

https://developers.gadaca.com/#api-Subscriptions-SubscriptionByCodeUnsubscribePut

Mismas caracterísitcas que la baja por id pero utilizando el código de la suscripción en vez del identificador.

Reactivar suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionReactivatePut

Se reactiva una suscripción utilizando el identificador de la misma.

Retorna un objeto de tipo suscripción.

Eliminar suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionDelete

Se elimina una suscripción utilizando el identificador de la misma.

Retorna un objeto de tipo suscripción.

Añadir pacientes a suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionUserListPost

Se añaden pacientes a una suscripción. Al igual que en la creación se añaden a través del campo users_ids.

Retorna un objeto de tipo suscripción.

Eliminar pacientes de suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionUserListDelete

Se eliminan pacientes a una suscripción. Al igual que en la creación se añaden a través del campo users_ids.

Retorna un objeto de tipo suscripción.

Recuperar suscripción

https://developers.gadaca.com/#api-Subscriptions-SubscriptionGet

Se recupera una suscripción mediante su id.

Retorna un objeto de tipo suscripción.

En este punto, se pueden recuperar también vía "include" otros datos relacionados con la suscripción como son:

• holder: incluye un campo con un objeto tipo usuario
• plan: incluye el plan al que pertenece la suscripción recuperada
• patients: incluye un campo "patients" con un listado de objetos tipo usuario que contiene los pacientes incluídos en la suscripción.

Recuperar suscripción por código

https://developers.gadaca.com/#api-Subscriptions-SubscriptionByCodePolicyGet

Se recupera una suscripción mediante su código.

Retorna un objeto de tipo suscripción.

Recuperar listado de suscripciones

https://developers.gadaca.com/#api-Subscriptions-SubscriptionListGet

Se recupera el listado de suscripciones relativas al dominio.

Retorna un listado de objetos tipo suscripción.

HTTP/1.1 200 OK
{
   "data": [
        {
            "object": "Subscription",
            "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "uuid": "123e4567-e89b-12d3-a456-426614174000",
            "apportionment_type_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "begin_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "billed_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "code": "HOM3HDB100000001",
            "commercial_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "currency_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "distributor_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "domain_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "duration": 5,
            "duration_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "end_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "external_id": "9192332234234-n23423",
            "free_tier_begin_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "free_tier_duration": 5,
            "free_tier_duration_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "free_tier_end_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "holder_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "is_autorenewable": true,
            "is_copayment_individual": true,
            "is_copayment_invoiced_instantly": false,
            "is_ended_by_promotional_code": true,
            "is_holder_signature_required": true,
            "is_invoice_generable": true,
            "is_payment_automatic": true,
            "level": 5,
            "name": "Unlimited",
            "permanence": 5,
            "permanence_end_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "permanence_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "plan_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "policy_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "price_quota": 23.12,
            "price_quota_per_user": 12.54,
            "price_upfront": 8.76,
            "price_upfront_per_user": 3.15,
            "promotional_code_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "status_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "users_limit": 6,
            "users_age_limit": 18,
            "users_over_age_limit": 2,
            "apportionment_type": {
                "data": {
                    "object": "Category",
                    "code": "monthly"
                }
            },
            "duration_unit": {
                "data": {
                    "object": "Category",
                    "code": "months"
                }
            },
            "free_tier_duration_unit": {
                "data": {
                    "object": "Category",
                    "code": "days"
                }
            },
            "permanence_unit": {
                "data": {
                    "object": "Category",
                    "code": "months"
                }
            },
            "status": {
                "data": {
                    "object": "Category",
                    "code": "active"
                }
            },
            "created_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "updated_at": {
                "date": "2017-06-26 21:00:02.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            }
        },
        {
            "object": "Subscription",
            "id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "uuid": "123e4567-e89b-12d3-a456-426614174000",
            "apportionment_type_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "begin_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "billed_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "code": "HOM3HDB100000001",
            "commercial_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "currency_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "distributor_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "domain_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "duration": 5,
            "duration_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "end_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "external_id": "9192332234234-n23423",
            "free_tier_begin_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "free_tier_duration": 5,
            "free_tier_duration_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "free_tier_end_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "holder_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "is_autorenewable": true,
            "is_copayment_individual": true,
            "is_copayment_invoiced_instantly": true,
            "is_ended_by_promotional_code": true,
            "is_holder_signature_required": true,
            "is_invoice_generable": true,
            "is_payment_automatic": true,
            "level": 5,
            "name": "Unlimited",
            "permanence": 5,
            "permanence_end_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "permanence_unit_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "plan_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "price_quota": 23.12,
            "price_quota_per_user": 12.54,
            "price_upfront": 8.76,
            "price_upfront_per_user": 3.15,
            "promotional_code_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "status_id": "xopxon45qlekj78m9gzy0avdbr96m37n",
            "users_limit": 6,
            "users_age_limit": 18,
            "users_over_age_limit": 2,
            "apportionment_type": {
                "data": {
                    "object": "Category",
                    "code": "monthly"
                }
            },
            "duration_unit": {
                "data": {
                    "object": "Category",
                    "code": "months"
                }
            },
            "free_tier_duration_unit": {
                "data": {
                    "object": "Category",
                    "code": "days"
                }
            },
            "permanence_unit": {
                "data": {
                    "object": "Category",
                    "code": "months"
                }
            },
            "status": {
                "data": {
                    "object": "Category",
                    "code": "active"
                }
            },
            "created_at": {
                "date": "2017-04-09 12:02:46.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            },
            "updated_at": {
                "date": "2017-06-26 21:00:02.000000",
                "timezone_type": 3,
                "timezone": "Europe/Madrid"
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 2,
            "count": 2,
            "per_page": 20,
            "current_page": 1,
            "total_pages": 1,
            "links": []
        }
    }
}

Gestión para distribuidores

Distribuidor Crear suscripción

https://developers.gadaca.com/#api-Distributors-DistributorSubscriptionPost

Campos importantes para la creación de una suscripción asociada a un distribuidor:

• code: (opcional) código que asignar a la suscripción, puede ser utilizado para almacenar el código de contrato del sistema a integrar
• external_id: (opcional) identificador del contrato en el sistema externo
• addressee: Nombre del destinatario
• commercial_id: Identificador del comercial del plan, se proporcionará.
• plan_id: identificador del plan a que asociar la suscripción.
• is_register_by_promotional_code: Se genera un código promocional con el que añadir el usuario principal a la suscripción. Se enviará dicho código en el email de alta.
• billed: Objeto billed con los datos de facturación de la persona que contrata la suscripción
• location: Objeto con los datos de la localización. Sobre todo importantes en country_id(Se proporciona) y el campo full_address en el que se indicará la dirección completa del destinatario de los dispositivos

Se retorna un objeto de tipo suscripción.

Distribuidor Dar de baja suscripción

https://developers.gadaca.com/#api-Distributors-DistributorSubscriptionUnsubscribePost](https://developers.gadaca.com/#api-Distributors-DistributorSubscriptionUnsubscribePost)

Campos importantes para dar de baja una suscripción asociada a un distribuidor:

• external_id: (opcional) identificador del contrato en el sistema externo
• subscription_id: Identificador de la suscripción generado por homedoctor en en momento de su creación

Se retorna un objeto de tipo suscripción.